@znight/openapi 0.0.0-stage → 0.1.0

package/dist/compiler.mjs

@@ -0,0 +1,2639 @@
+import { a as METHOD_ORDER, c as canonicalJson, d as isResponseStatus, i as MEDIA_TYPE, l as compareStrings, m as schemaRef, n as ERROR_RESPONSES, o as OPENAPI_VERSION, p as reasonPhrase, r as HEADER_NAME, s as OPERATION_ID, t as ERROR_COMPONENTS, u as componentName } from "./shared-BZxtyaB0.mjs";
+import { createHash } from "node:crypto";
+// src/compiler/model.ts
+/** Name of the extension (key of `metadata.extensions`). */
+const EXTENSION_NAME = "openapi";
+/** Canonical identities of the decorators and functions of `@znight/openapi`. */
+const Ids = Object.freeze({
+	OpenApiDocument: "@znight/openapi#OpenApiDocument",
+	ApiOperation: "@znight/openapi#ApiOperation",
+	ApiTags: "@znight/openapi#ApiTags",
+	ApiResponse: "@znight/openapi#ApiResponse",
+	ApiBody: "@znight/openapi#ApiBody",
+	ApiQuery: "@znight/openapi#ApiQuery",
+	ApiHeader: "@znight/openapi#ApiHeader",
+	ApiSecurity: "@znight/openapi#ApiSecurity",
+	ApiExclude: "@znight/openapi#ApiExclude",
+	securityScheme: "@znight/openapi#securityScheme"
+});
+/** Identities of `@znight/http` read by the extension. */
+const HttpIds = Object.freeze({
+	Controller: "@znight/http#Controller",
+	createRouteDecorator: "@znight/http#createRouteDecorator",
+	HttpResponse: "@znight/http#HttpResponse",
+	FileBody: "@znight/http#FileBody",
+	SseEvent: "@znight/http#SseEvent",
+	SseBody: "@znight/http#SseBody"
+});
+/** Route method decorators of `@znight/http` (a method carrying one is a route handler). */
+const ROUTE_DECORATORS = /* @__PURE__ */ new Set([
+	"@znight/http#Get",
+	"@znight/http#Post",
+	"@znight/http#Put",
+	"@znight/http#Patch",
+	"@znight/http#Delete",
+	"@znight/http#Head",
+	"@znight/http#Options",
+	"@znight/http#All",
+	"@znight/http#Sse"
+]);
+/** Error codes used by the extension (see `ErrorCode` in `@znight/core`). */
+const Codes = Object.freeze({
+	InvalidDecorator: "ZNIGHT005",
+	InvalidOpenApiDefinition: "ZNIGHT030",
+	UndocumentedResponse: "ZNIGHT031",
+	UnrepresentableType: "ZNIGHT032",
+	DuplicateOperationId: "ZNIGHT033",
+	SchemaNameConflict: "ZNIGHT034",
+	InconsistentOperation: "ZNIGHT035",
+	InvalidSecurityRequirement: "ZNIGHT036"
+});
+/** Generic aliases meaning "the Standard Schema S" (`z.output<typeof S>`), checked against the installed libraries. */
+const SCHEMA_ALIASES = Object.freeze({
+	"zod#output": "output",
+	"zod#infer": "output",
+	"zod#input": "input",
+	"zod/v4#output": "output",
+	"zod/v4#infer": "output",
+	"zod/v4#input": "input",
+	"valibot#InferOutput": "output",
+	"valibot#InferInput": "input",
+	"@znight/http#InferSchemaOutput": "output",
+	"@znight/http#InferSchemaInput": "input",
+	"@standard-schema/spec#StandardSchemaV1.InferOutput": "output",
+	"@standard-schema/spec#StandardSchemaV1.InferInput": "input"
+});
+/** ArkType: `typeof S.infer` / `typeof S.inferIn`. */
+const SCHEMA_MEMBERS = Object.freeze({
+	infer: "output",
+	inferIn: "input"
+});
+/** Types kept as references by the shape resolver (bodies of special responses). */
+const KEEP = Object.freeze([
+	HttpIds.HttpResponse,
+	HttpIds.FileBody,
+	HttpIds.SseEvent,
+	HttpIds.SseBody,
+	"globalThis#AsyncIterable",
+	"globalThis#AsyncIterableIterator",
+	"globalThis#AsyncGenerator",
+	"globalThis#Response"
+]);
+// src/compiler/analyze.ts
+/** `analyzeClass` of the extension. */
+function analyzeOpenApiClass(cls, ctx) {
+	const owned = (decorators) => decorators.filter((decorator) => decorator.owner === EXTENSION_NAME);
+	const document = cls.decorators.find((decorator) => decorator.identity === Ids.OpenApiDocument);
+	const controller = cls.decorators.some((decorator) => decorator.identity === HttpIds.Controller);
+	const members = [...cls.methods.map((method) => ({
+		decorators: owned(method.decorators),
+		method
+	})), ...cls.properties.map((property) => ({
+		decorators: owned(property.decorators),
+		method: void 0
+	}))];
+	const misplaced = (decorator, message, hints) => {
+		ctx.report({
+			code: Codes.InvalidOpenApiDefinition,
+			severity: "error",
+			message,
+			location: decorator.location,
+			hints
+		});
+	};
+	if (document !== void 0) {
+		if (controller) misplaced(document, `@OpenApiDocument goes on a class of its own, not on the controller ${cls.displayName}`, ["Declare it on an empty class: @OpenApiDocument({...}) export class Api {}"]);
+		for (const decorator of owned(cls.decorators)) if (decorator !== document && !controller) misplaced(decorator, `@${decorator.name} applies to controllers and route handlers, not to the @OpenApiDocument class`, []);
+		ctx.store({
+			kind: "document",
+			identity: cls.identity,
+			displayName: cls.displayName,
+			location: document.location
+		});
+		if (!controller) return;
+	}
+	if (!controller) {
+		const hints = cls.decorators.some((decorator) => decorator.identity === "@znight/messaging#Consumer") ? ["Message consumers are not documented by OpenAPI (AsyncAPI is not supported in v0.1)"] : ["Add @Controller() to the class, or remove the decorator"];
+		for (const decorator of owned(cls.decorators)) misplaced(decorator, `@${decorator.name} applies to controllers: ${cls.displayName} is not a @Controller`, hints);
+		for (const member of members) for (const decorator of member.decorators) misplaced(decorator, `@${decorator.name} applies to route handlers: ${cls.displayName} is not a @Controller`, hints);
+		return;
+	}
+	for (const member of members) {
+		if (member.method?.decorators.some((decorator) => decorator.identity !== void 0 && ROUTE_DECORATORS.has(decorator.identity)) === true) continue;
+		for (const decorator of member.decorators) misplaced(decorator, `@${decorator.name} applies to route handlers: ${cls.displayName}.${member.method?.name ?? "this member"} has no route decorator (@Get, @Post...)`, ["Add a route decorator, or move the decorator to a route handler"]);
+	}
+	ctx.store({
+		kind: "controller",
+		identity: cls.identity,
+		displayName: cls.displayName
+	});
+}
+// src/compiler/values.ts
+/** `true` for a `ValueRef` (a reference to an exported binding, nested in an evaluated value). */
+function isRef(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype !== Object.prototype && prototype !== null && value.kind === "ref";
+}
+/** `true` for an evaluated object literal (not an array, not a reference). */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && !isRef(value);
+}
+/** The value when it is JSON (no `undefined` inside objects is kept, no bigint, no reference). */
+function toJson(value) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+	if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
+	if (value === void 0 || typeof value === "bigint" || isRef(value)) return void 0;
+	if (Array.isArray(value)) {
+		const items = [];
+		for (const item of value) {
+			const json = toJson(item);
+			if (json === void 0) return void 0;
+			items.push(json);
+		}
+		return items;
+	}
+	const result = {};
+	for (const [key, item] of Object.entries(value)) {
+		if (item === void 0) continue;
+		const json = toJson(item);
+		if (json === void 0) return void 0;
+		result[key] = json;
+	}
+	return result;
+}
+/** The first `$znight` key found in a value (reserved), as a path (`info.x.$znight`). */
+function findReservedKey(value, path = "") {
+	if (Array.isArray(value)) {
+		for (const [index, item] of value.entries()) {
+			const found = findReservedKey(item, `${path}[${index}]`);
+			if (found !== void 0) return found;
+		}
+		return;
+	}
+	if (!isRecord(value)) return void 0;
+	for (const [key, item] of Object.entries(value)) {
+		const where = path === "" ? key : `${path}.${key}`;
+		if (key === "$znight") return where;
+		const found = findReservedKey(item, where);
+		if (found !== void 0) return found;
+	}
+}
+/** A short description for messages. */
+function describe(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "an array";
+	if (isRef(value)) return `a reference to '${value.text}'`;
+	if (typeof value === "object") return "an object";
+	if (typeof value === "string") return JSON.stringify(value);
+	return String(value);
+}
+/** Absolute URL (`https://...`, `mailto:`...). */
+function isAbsoluteUrl(value) {
+	return URL.canParse(value);
+}
+/** Absolute or relative URL (servers: `/api`, `https://api.example.com/v1`). */
+function isUrlReference(value) {
+	return value !== "" && !/\s/.test(value) && (URL.canParse(value) || URL.canParse(value, "https://example.com"));
+}
+// src/compiler/document.ts
+const OPTION_KEYS = /* @__PURE__ */ new Set([
+	"info",
+	"servers",
+	"tags",
+	"externalDocs",
+	"security",
+	"decisions",
+	"operationIds",
+	"errors",
+	"strict",
+	"jsdoc",
+	"extensions"
+]);
+const INFO_KEYS = /* @__PURE__ */ new Set([
+	"title",
+	"version",
+	"summary",
+	"description",
+	"termsOfService",
+	"contact",
+	"license"
+]);
+const SPDX = /^[A-Za-z0-9.+-]+(?:\s+(?:AND|OR|WITH)\s+[A-Za-z0-9.+-]+)*$/;
+/** Security schemes declared with `securityScheme(name, definition)`, by identity of their `const`. */
+var SchemeRegistry = class {
+	#ctx;
+	#schemes = /* @__PURE__ */ new Map();
+	#byName = /* @__PURE__ */ new Map();
+	#definitions;
+	/** Schemes referenced by the document, by name. */
+	used = /* @__PURE__ */ new Map();
+	constructor(ctx) {
+		this.#ctx = ctx;
+		this.#definitions = new Map(ctx.definitionsOf(Ids.securityScheme).map((definition) => [definition.identity, definition]));
+	}
+	/** The scheme a reference points to (`undefined` and a ZNIGHT036 when it is not a scheme). */
+	resolve(ref) {
+		const identity = ref.identity;
+		if (identity !== void 0 && this.#schemes.has(identity)) return this.#schemes.get(identity) ?? void 0;
+		const definition = identity === void 0 ? void 0 : this.#definitions.get(identity);
+		if (definition === void 0 || identity === void 0) {
+			this.#ctx.report({
+				code: Codes.InvalidSecurityRequirement,
+				severity: "error",
+				message: `${ref.text} is not a security scheme declared with securityScheme()`,
+				location: ref.location,
+				hints: ["Declare it: export const ApiKey = securityScheme('apiKey', { type: 'apiKey', in: 'header', name: 'x-api-key' })"]
+			});
+			return;
+		}
+		const scheme = this.#parse(definition);
+		this.#schemes.set(identity, scheme ?? null);
+		return scheme;
+	}
+	#parse(definition) {
+		const [nameArg, definitionArg] = definition.args;
+		const name = nameArg?.evaluated ? nameArg.value : void 0;
+		const value = definitionArg?.evaluated ? definitionArg.value : void 0;
+		const malformed = (message, location = definition.call) => {
+			this.#ctx.report({
+				code: Codes.InvalidOpenApiDefinition,
+				severity: "error",
+				message: `Invalid security scheme ${definition.displayName}: ${message}`,
+				location,
+				hints: ["securityScheme(name, definition) takes a static name and an OpenAPI Security Scheme Object"]
+			});
+		};
+		if (typeof name !== "string" || !/^[A-Za-z0-9._-]+$/.test(name)) return malformed("the name must be a static string of [A-Za-z0-9._-]", nameArg?.location);
+		if (!isRecord(value)) return malformed("the definition must be a static object", definitionArg?.location);
+		const reserved = findReservedKey(value);
+		if (reserved !== void 0) return malformed(`"$znight" is a reserved key (${reserved})`, definitionArg?.location);
+		const json = toJson(value);
+		if (!isRecord(json)) return malformed("the definition must be JSON", definitionArg?.location);
+		const where = definitionArg?.location;
+		const text = (key, required) => {
+			const field = json[key];
+			if (field === void 0 && !required) return void 0;
+			if (typeof field !== "string" || field === "") throw new SchemeError(`"${key}" must be a non-empty string`);
+			return field;
+		};
+		let scopes;
+		try {
+			for (const key of Object.keys(json)) if (!ALLOWED_SCHEME_KEYS[String(json["type"])]?.has(key) && !key.startsWith("x-") && key !== "description") throw new SchemeError(`unknown field "${key}" for a ${String(json["type"])} scheme`);
+			switch (json["type"]) {
+				case "apiKey": {
+					text("name", true);
+					const location = text("in", true);
+					if (location !== "query" && location !== "header" && location !== "cookie") throw new SchemeError("\"in\" must be \"query\", \"header\" or \"cookie\"");
+					break;
+				}
+				case "http":
+					text("scheme", true);
+					text("bearerFormat", false);
+					break;
+				case "oauth2": {
+					const flows = json["flows"];
+					if (!isRecord(flows) || Object.keys(flows).length === 0) throw new SchemeError("\"flows\" must declare a flow");
+					scopes = /* @__PURE__ */ new Set();
+					for (const [flow, body] of Object.entries(flows)) {
+						if (!FLOW_URLS[flow]) throw new SchemeError(`unknown flow "${flow}"`);
+						if (!isRecord(body) || !isRecord(body["scopes"])) throw new SchemeError(`the ${flow} flow needs "scopes"`);
+						for (const url of FLOW_URLS[flow] ?? []) {
+							const field = body[url];
+							if (typeof field !== "string" || !isUrlReference(field)) throw new SchemeError(`the ${flow} flow needs a "${url}" URL`);
+						}
+						for (const scope of Object.keys(body["scopes"])) scopes.add(scope);
+					}
+					break;
+				}
+				case "openIdConnect":
+					if (!isUrlReference(text("openIdConnectUrl", true))) throw new SchemeError("\"openIdConnectUrl\" must be a URL");
+					break;
+				case "mutualTLS": break;
+				default: throw new SchemeError("\"type\" must be \"apiKey\", \"http\", \"oauth2\", \"openIdConnect\" or \"mutualTLS\"");
+			}
+		} catch (error) {
+			if (error instanceof SchemeError) return malformed(error.message, where);
+			throw error;
+		}
+		const scheme = {
+			identity: definition.identity,
+			name,
+			definition: json,
+			location: definition.location,
+			scopes,
+			scoped: json["type"] === "oauth2" || json["type"] === "openIdConnect"
+		};
+		const other = this.#byName.get(name);
+		if (other !== void 0 && JSON.stringify(other.definition) !== JSON.stringify(scheme.definition)) {
+			this.#ctx.report({
+				code: Codes.InvalidSecurityRequirement,
+				severity: "error",
+				message: `Two security schemes are named "${name}" with different definitions: ${definition.displayName} and ${other.identity}`,
+				location: definition.location,
+				related: [{
+					message: "the other scheme",
+					location: other.location
+				}],
+				hints: ["Give each scheme its own name, or reuse one declaration"]
+			});
+			return;
+		}
+		this.#byName.set(name, scheme);
+		return scheme;
+	}
+	/**
+	* Resolves a requirement input (`ApiKey`, `[Bearer, Tenant]`, `{ scheme, scopes }`) to schemes.
+	* Reports ZNIGHT036 and returns `undefined` when it is invalid.
+	*/
+	requirement(value, location) {
+		const report = (message, hints = REQUIREMENT_HINTS) => {
+			this.#ctx.report({
+				code: Codes.InvalidSecurityRequirement,
+				severity: "error",
+				message,
+				location,
+				hints
+			});
+		};
+		const one = (item, scopes) => {
+			if (!isRef(item)) return report(`${describe(item)} is not a security scheme declared with securityScheme()`);
+			const scheme = this.resolve(item);
+			if (scheme === void 0) return void 0;
+			if (scopes !== void 0 && scopes.length > 0) {
+				if (!scheme.scoped) return report(`Scopes are only allowed on oauth2 and openIdConnect schemes, not on "${scheme.name}" (${String(scheme.definition.type)})`, ["Remove the scopes, or use an oauth2 / openIdConnect scheme"]);
+				const unknown = scheme.scopes === void 0 ? [] : scopes.filter((scope) => !scheme.scopes?.has(scope));
+				if (unknown.length > 0) return report(`The scope${unknown.length > 1 ? "s" : ""} ${unknown.map((scope) => `"${scope}"`).join(", ")} ${unknown.length > 1 ? "are" : "is"} not declared by the flows of "${scheme.name}"`, [`Declared scopes: ${[...scheme.scopes ?? []].join(", ") || "none"}`]);
+			}
+			return {
+				scheme,
+				scopes
+			};
+		};
+		if (Array.isArray(value)) {
+			const items = [];
+			for (const item of value) {
+				const resolved = one(item, void 0);
+				if (resolved === void 0) return void 0;
+				items.push(resolved);
+			}
+			return items;
+		}
+		if (isRecord(value)) {
+			const scopes = value["scopes"];
+			if (!Array.isArray(scopes) || !scopes.every((scope) => typeof scope === "string")) return report("{ scheme, scopes } needs a static array of scope names");
+			const resolved = one(value["scheme"], scopes);
+			return resolved === void 0 ? void 0 : [resolved];
+		}
+		const resolved = one(value, void 0);
+		return resolved === void 0 ? void 0 : [resolved];
+	}
+	/** Requirement objects of resolved requirements (`scopes` overrides every scheme's scopes). */
+	objects(requirements, scopes) {
+		return requirements.map((requirement) => {
+			const object = {};
+			for (const { scheme, scopes: own } of requirement) {
+				this.used.set(scheme.name, scheme);
+				object[scheme.name] = [...scopes ?? own ?? []];
+			}
+			return object;
+		});
+	}
+};
+var SchemeError = class extends Error {};
+const REQUIREMENT_HINTS = ["A requirement is a scheme (ApiKey), several schemes that all apply ([Bearer, Tenant]) or { scheme: OAuth, scopes: [...] }"];
+const ALLOWED_SCHEME_KEYS = {
+	apiKey: /* @__PURE__ */ new Set([
+		"type",
+		"name",
+		"in"
+	]),
+	http: /* @__PURE__ */ new Set([
+		"type",
+		"scheme",
+		"bearerFormat"
+	]),
+	oauth2: /* @__PURE__ */ new Set(["type", "flows"]),
+	openIdConnect: /* @__PURE__ */ new Set(["type", "openIdConnectUrl"]),
+	mutualTLS: /* @__PURE__ */ new Set(["type"])
+};
+const FLOW_URLS = {
+	implicit: ["authorizationUrl"],
+	password: ["tokenUrl"],
+	clientCredentials: ["tokenUrl"],
+	authorizationCode: ["authorizationUrl", "tokenUrl"]
+};
+/** Reads and checks the `@OpenApiDocument` options (and the defaults of `package.json`). */
+function readDocument(ctx, schemes) {
+	const documents = ctx.stored.filter((data) => data.kind === "document");
+	for (const extra of documents.slice(1)) {
+		const first = documents[0];
+		ctx.report({
+			code: Codes.InvalidOpenApiDefinition,
+			severity: "error",
+			message: `An application has one @OpenApiDocument: ${extra.displayName} and ${first?.displayName ?? "?"} both declare one`,
+			location: extra.location,
+			...first === void 0 ? {} : { related: [{
+				message: "the other @OpenApiDocument",
+				location: first.location
+			}] },
+			hints: ["Keep one class with @OpenApiDocument; filter operations with OpenApiPlugin.configure({ filter })"]
+		});
+	}
+	const stored = documents[0];
+	const cls = stored === void 0 ? void 0 : ctx.classInfo(stored.identity);
+	const decorator = cls?.decorators.find((candidate) => candidate.identity === Ids.OpenApiDocument);
+	const arg = decorator?.args[0];
+	const value = arg?.evaluated === true ? arg.value : void 0;
+	const location = arg?.location ?? decorator?.location;
+	const invalid = (message, hints = []) => {
+		ctx.report({
+			code: Codes.InvalidOpenApiDefinition,
+			severity: "error",
+			message: `Invalid @OpenApiDocument options: ${message}`,
+			...location === void 0 ? {} : { location },
+			hints
+		});
+	};
+	const options = isRecord(value) ? value : {};
+	if (value !== void 0 && !isRecord(value)) invalid(`expected an object, received ${describe(value)}`);
+	for (const key of Object.keys(options)) if (!OPTION_KEYS.has(key)) invalid(`unknown option "${key}"`, [`Options: ${[...OPTION_KEYS].join(", ")}`]);
+	const reserved = findReservedKey(options);
+	if (reserved !== void 0) invalid(`"$znight" is a reserved key (${reserved})`);
+	const bool = (key, fallback) => {
+		const option = options[key];
+		if (option === void 0) return fallback;
+		if (typeof option !== "boolean") {
+			invalid(`"${key}" must be true or false`);
+			return fallback;
+		}
+		return option;
+	};
+	const json = (key) => {
+		const option = options[key];
+		if (option === void 0) return void 0;
+		const converted = toJson(option);
+		if (converted === void 0) invalid(`"${key}" must be a static JSON value`);
+		return converted;
+	};
+	const doc = bool("jsdoc", true) ? cls?.doc : void 0;
+	const manifest = ctx.project.rootPackage?.json ?? {};
+	const infoOption = json("info");
+	const info = {};
+	if (infoOption !== void 0 && !isRecord(infoOption)) invalid("\"info\" must be an object");
+	const given = isRecord(infoOption) ? infoOption : {};
+	for (const key of Object.keys(given)) if (!INFO_KEYS.has(key) && !key.startsWith("x-")) invalid(`unknown field "info.${key}"`);
+	const manifestString = (key) => {
+		const field = manifest[key];
+		return typeof field === "string" && field !== "" ? field : void 0;
+	};
+	const title = given["title"] ?? doc?.summary ?? manifestString("name") ?? "API";
+	const version = given["version"] ?? manifestString("version") ?? "0.0.0";
+	if (typeof title !== "string" || title === "") invalid("\"info.title\" must be a non-empty string");
+	if (typeof version !== "string" || version === "") invalid("\"info.version\" must be a non-empty string");
+	info["title"] = typeof title === "string" ? title : "API";
+	info["version"] = typeof version === "string" ? version : "0.0.0";
+	for (const key of [
+		"summary",
+		"termsOfService",
+		"contact",
+		"license"
+	]) if (given[key] !== void 0) info[key] = given[key];
+	const description = given["description"] ?? doc?.description ?? manifestString("description");
+	if (description !== void 0) info["description"] = description;
+	if (info["license"] === void 0) {
+		const license = manifestString("license");
+		if (license !== void 0 && SPDX.test(license) && license !== "UNLICENSED") info["license"] = {
+			name: license,
+			identifier: license
+		};
+	}
+	for (const [key, field] of Object.entries(given)) if (key.startsWith("x-")) info[key] = field;
+	checkInfo(info, invalid);
+	const servers = json("servers");
+	if (servers !== void 0) {
+		if (!Array.isArray(servers) || servers.some((server) => !isRecord(server) || !isUrlReference(String(server["url"])))) invalid("\"servers\" must be an array of { url, description?, variables? } with valid URLs");
+	}
+	const tagsOption = json("tags");
+	const tags = [];
+	if (tagsOption !== void 0) {
+		if (Array.isArray(tagsOption)) {
+			const seen = /* @__PURE__ */ new Set();
+			for (const tag of tagsOption) {
+				if (!isRecord(tag) || typeof tag["name"] !== "string" || tag["name"] === "") {
+					invalid("every tag needs a non-empty \"name\"");
+					continue;
+				}
+				if (seen.has(tag["name"])) invalid(`the tag "${tag["name"]}" is declared twice`);
+				seen.add(tag["name"]);
+				tags.push(tag);
+			}
+		} else invalid("\"tags\" must be an array of { name, description? }");
+	}
+	const externalDocs = json("externalDocs");
+	if (externalDocs !== void 0 && (!isRecord(externalDocs) || !isAbsoluteUrl(String(externalDocs["url"])))) invalid("\"externalDocs\" must be { url, description? } with an absolute URL");
+	const extensionsOption = json("extensions");
+	const extensions = {};
+	if (extensionsOption !== void 0) {
+		if (isRecord(extensionsOption)) for (const [key, field] of Object.entries(extensionsOption)) if (key.startsWith("x-")) extensions[key] = field;
+		else invalid(`the extension "${key}" must start with "x-"`);
+		else invalid("\"extensions\" must be an object of x-* fields");
+	}
+	const style = options["operationIds"] ?? "controller.handler";
+	if (style !== "controller.handler" && style !== "handler" && style !== "Controller_handler") invalid("\"operationIds\" must be \"controller.handler\", \"handler\" or \"Controller_handler\"");
+	let errors = {
+		contentType: "application/json",
+		schema: void 0
+	};
+	const errorsOption = options["errors"];
+	if (errorsOption === false) errors = false;
+	else if (isRecord(errorsOption)) {
+		const schema = errorsOption["schema"];
+		const contentType = errorsOption["contentType"] ?? "application/json";
+		if (!isRef(schema)) invalid("\"errors.schema\" must be a Standard Schema (an exported schema)");
+		if (typeof contentType !== "string") invalid("\"errors.contentType\" must be a media type");
+		errors = {
+			contentType: typeof contentType === "string" ? contentType : "application/json",
+			schema: isRef(schema) ? schema : void 0
+		};
+	} else if (errorsOption !== void 0 && errorsOption !== true) invalid("\"errors\" must be true, false or { schema, contentType? }");
+	const where = location ?? decorator?.location;
+	let security;
+	const securityOption = options["security"];
+	if (securityOption !== void 0 && where !== void 0) {
+		if (Array.isArray(securityOption)) {
+			security = [];
+			for (const item of securityOption) {
+				const requirement = schemes.requirement(item, where);
+				if (requirement !== void 0) security.push(requirement);
+			}
+		} else invalid("\"security\" must be an array of requirements");
+	}
+	const decisions = readDecisions(ctx, schemes, options["decisions"], where, invalid);
+	return {
+		identity: stored?.identity,
+		location: decorator?.location,
+		info,
+		servers: Array.isArray(servers) ? servers : void 0,
+		tags,
+		externalDocs,
+		security,
+		decisions,
+		operationIds: typeof style === "string" ? style : "controller.handler",
+		errors,
+		strict: bool("strict", false),
+		jsdoc: bool("jsdoc", true),
+		extensions
+	};
+}
+function checkInfo(info, invalid) {
+	const terms = info["termsOfService"];
+	if (terms !== void 0 && (typeof terms !== "string" || !isAbsoluteUrl(terms))) invalid("\"info.termsOfService\" must be an absolute URL");
+	const contact = info["contact"];
+	if (contact !== void 0) {
+		if (isRecord(contact)) {
+			if (contact["url"] !== void 0 && !isAbsoluteUrl(String(contact["url"]))) invalid("\"info.contact.url\" must be an absolute URL");
+			if (contact["email"] !== void 0 && !/^[^\s@]+@[^\s@]+$/.test(String(contact["email"]))) invalid("\"info.contact.email\" must be an email address");
+		} else invalid("\"info.contact\" must be { name?, url?, email? }");
+	}
+	const license = info["license"];
+	if (license !== void 0) {
+		if (!isRecord(license) || typeof license["name"] !== "string" || license["name"] === "") invalid("\"info.license\" must be { name, identifier? } or { name, url? }");
+		else {
+			if (license["identifier"] !== void 0 && license["url"] !== void 0) invalid("\"info.license\" takes \"identifier\" or \"url\", not both");
+			if (license["identifier"] !== void 0 && !SPDX.test(String(license["identifier"]))) invalid("\"info.license.identifier\" must be an SPDX expression (MIT, Apache-2.0...)");
+			if (license["url"] !== void 0 && !isAbsoluteUrl(String(license["url"]))) invalid("\"info.license.url\" must be an absolute URL");
+		}
+	}
+}
+function readDecisions(ctx, schemes, value, location, invalid) {
+	if (value === void 0 || location === void 0) return [];
+	if (!Array.isArray(value)) {
+		invalid("\"decisions\" must be an array of { when, security, scopes? }");
+		return [];
+	}
+	const routeDecorators = new Set(ctx.definitionsOf(HttpIds.createRouteDecorator).map((definition) => definition.identity));
+	const decisions = [];
+	for (const entry of value) {
+		if (!isRecord(entry)) {
+			invalid("every decision is { when, security, scopes? }");
+			continue;
+		}
+		const when = entry["when"];
+		if (!isRef(when) || when.identity === void 0 || !routeDecorators.has(when.identity)) {
+			ctx.report({
+				code: Codes.InvalidSecurityRequirement,
+				severity: "error",
+				message: `decisions[].when must be a route decorator created with createRouteDecorator(), not ${describe(when)}`,
+				location: isRef(when) ? when.location : location,
+				hints: ["Declare it: export const Public = createRouteDecorator('public')"]
+			});
+			continue;
+		}
+		const scopes = entry["scopes"];
+		if (scopes !== void 0 && scopes !== "value") {
+			ctx.report({
+				code: Codes.InvalidSecurityRequirement,
+				severity: "error",
+				message: `decisions[].scopes must be 'value' (received ${describe(scopes)})`,
+				location: when.location,
+				hints: ["{ when: Roles, security: [OAuth], scopes: 'value' } turns @Roles(['admin']) into the scopes ['admin']"]
+			});
+			continue;
+		}
+		const security = entry["security"];
+		if (!Array.isArray(security)) {
+			ctx.report({
+				code: Codes.InvalidSecurityRequirement,
+				severity: "error",
+				message: `decisions[].security of ${when.text} must be an array of requirements ([] means public)`,
+				location: when.location
+			});
+			continue;
+		}
+		const requirements = [];
+		let valid = true;
+		for (const item of security) {
+			const requirement = schemes.requirement(item, when.location);
+			if (requirement === void 0) valid = false;
+			else requirements.push(requirement);
+		}
+		if (!valid) continue;
+		decisions.push({
+			identity: when.identity,
+			text: when.text,
+			location: when.location,
+			security: requirements,
+			scopesFromValue: scopes === "value",
+			used: false
+		});
+	}
+	return decisions;
+}
+/** The document template: `openapi`, `info`, declared `servers`, `tags`... and the default security. */
+function documentTemplate(model, security) {
+	const template = {
+		openapi: OPENAPI_VERSION,
+		info: model.info
+	};
+	if (model.servers !== void 0) template["servers"] = model.servers;
+	if (model.tags.length > 0) template["tags"] = model.tags;
+	if (model.externalDocs !== void 0) template["externalDocs"] = model.externalDocs;
+	if (security !== void 0) template["security"] = security;
+	for (const [key, value] of Object.entries(model.extensions)) template[key] = value;
+	return template;
+}
+// src/compiler/operations.ts
+const ALL_METHODS = [
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE"
+];
+const IGNORED_HEADERS = /* @__PURE__ */ new Set([
+	"accept",
+	"content-type",
+	"authorization"
+]);
+/** Builds every operation of the application (sorted by path, then method) and the tag descriptions. */
+function buildOperations(input) {
+	const { ctx } = input;
+	const controllers = [...ctx.graph.extensions.find((extension) => extension.name === "http")?.stored ?? []].sort((a, b) => compareStrings(a.token, b.token));
+	const explicit = /* @__PURE__ */ new Set();
+	for (const controller of controllers) for (const route of controller.routes) if (route.method !== "ALL") explicit.add(`${route.method} ${pathShape(route.fullPath)}`);
+	const operations = [];
+	const tagDescriptions = {};
+	for (const controller of controllers) {
+		const cls = ctx.classInfo(controller.identity);
+		const classDecorators = owned(cls?.decorators);
+		if (excluded(ctx, classDecorators, controller.displayName)) continue;
+		const defaultTag = controller.displayName.replace(/Controller$/, "") || controller.displayName;
+		const doc = input.document.jsdoc ? cls?.doc : void 0;
+		const classTags = tagsOf(ctx, classDecorators);
+		if (classTags.length === 0 && doc !== void 0 && doc.text !== "") tagDescriptions[defaultTag] = doc.text;
+		for (const route of controller.routes) {
+			if (!route.complete) continue;
+			const method = cls?.methods.find((candidate) => candidate.name === route.handler && !candidate.static);
+			const methodDecorators = owned(method?.decorators);
+			if (excluded(ctx, methodDecorators, `${controller.displayName}.${route.handler}`)) continue;
+			const methods = route.method === "ALL" ? ALL_METHODS.filter((m) => !explicit.has(`${m} ${pathShape(route.fullPath)}`)) : [route.method];
+			for (const httpMethod of methods) operations.push(new OperationBuilder(input, {
+				controller,
+				route,
+				httpMethod,
+				cls,
+				method,
+				classDecorators,
+				methodDecorators,
+				classTags,
+				defaultTag
+			}).build());
+		}
+	}
+	checkDuplicateIds(ctx, operations);
+	unifyPathTemplates(ctx, operations);
+	for (const decision of input.document.decisions) {
+		if (decision.used) continue;
+		ctx.report({
+			code: Codes.InvalidSecurityRequirement,
+			severity: "warning",
+			message: `The security decision on ${decision.text} applies to no route`,
+			location: decision.location,
+			hints: ["Remove the decision, or apply the decorator to the routes it describes"]
+		});
+	}
+	operations.sort((a, b) => compareStrings(a.path, b.path) || METHOD_ORDER.indexOf(a.method) - METHOD_ORDER.indexOf(b.method));
+	return {
+		operations,
+		tagDescriptions
+	};
+}
+/**
+* `/books/{id}` from `/books/:id`; the trailing wildcard is `{wildcard}` (`{wildcard_1}`... when a
+* parameter of the path is named `wildcard`).
+*/
+function pathTemplate(fullPath) {
+	const wildcard = wildcardName(fullPath);
+	return fullPath.split("/").map((segment) => {
+		if (segment.startsWith(":")) return `{${segment.slice(1)}}`;
+		return segment === "*" ? `{${wildcard}}` : segment;
+	}).join("/");
+}
+/** The name of the wildcard parameter of a path: `wildcard`, unless a `:wildcard` parameter exists. */
+function wildcardName(fullPath) {
+	const names = new Set(fullPath.split("/").filter((segment) => segment.startsWith(":")).map((segment) => segment.slice(1)));
+	let name = "wildcard";
+	for (let index = 1; names.has(name); index++) name = `wildcard_${index}`;
+	return name;
+}
+/** Names of the parameters of a path template, in order. */
+function templateNames(template) {
+	return [...template.matchAll(/\{([^}]*)\}/g)].map((match) => match[1]);
+}
+/**
+* OpenAPI forbids two templates of one path (`/books/{id}` and `/books/{bookId}`): the operations of
+* such a path are documented under one template (the first one, or the one a whole-path schema
+* names), with a ZNIGHT035 warning.
+*/
+function unifyPathTemplates(ctx, operations) {
+	const groups = /* @__PURE__ */ new Map();
+	operations.forEach((operation, index) => {
+		const shape = operation.path.replace(/\{[^}]*\}/g, "{}");
+		const group = groups.get(shape);
+		if (group === void 0) groups.set(shape, [index]);
+		else group.push(index);
+	});
+	for (const indexes of groups.values()) {
+		const group = indexes.map((index) => operations[index]);
+		const templates = [...new Set(group.map((operation) => operation.path))].sort(compareStrings);
+		if (templates.length < 2) continue;
+		const canonical = [...group.filter(hasPathPlaceholder).map((operation) => operation.path)].sort(compareStrings)[0] ?? templates[0];
+		const target = templateNames(canonical);
+		const renamed = [];
+		for (const index of indexes) {
+			const operation = operations[index];
+			if (operation.path === canonical || hasPathPlaceholder(operation)) continue;
+			const names = new Map(templateNames(operation.path).map((name, position) => [name, target[position]]));
+			for (const parameter of operation.operation["parameters"] ?? []) {
+				const name = parameter["name"];
+				if (parameter["in"] === "path" && typeof name === "string" && names.has(name)) parameter["name"] = names.get(name);
+			}
+			operations[index] = {
+				...operation,
+				path: canonical
+			};
+			renamed.push(operation);
+		}
+		const first = renamed[0] ?? group[0];
+		const kept = group.filter((operation) => operation.path !== canonical && hasPathPlaceholder(operation));
+		ctx.report({
+			code: Codes.InconsistentOperation,
+			severity: "warning",
+			message: `The routes of one path name its parameters differently (${group.map((operation) => operation.label).join(", ")}): OpenAPI forbids two templates of one path, ${kept.length === 0 ? `documented as ${canonical}` : `the whole-path schemas keep ${kept.map((operation) => operation.path).join(", ")}`}`,
+			location: first.location,
+			related: group.filter((operation) => operation !== first).map((operation) => ({
+				message: operation.label,
+				location: operation.location
+			})),
+			hints: ["Give the parameters the same names on every route of the path"]
+		});
+	}
+}
+/** Whether the path parameters of an operation come from a whole-path schema (`@Param(Schema)`). */
+function hasPathPlaceholder(operation) {
+	return (operation.operation["parameters"] ?? []).some((parameter) => parameter["$znight"] === "parameters" && parameter["in"] === "path");
+}
+function pathShape(fullPath) {
+	return fullPath.split("/").map((segment) => segment.startsWith(":") ? ":" : segment).join("/");
+}
+function owned(decorators) {
+	return (decorators ?? []).filter((decorator) => decorator.owner === EXTENSION_NAME);
+}
+function excluded(ctx, decorators, target) {
+	const exclude = decorators.find((decorator) => decorator.identity === Ids.ApiExclude);
+	if (exclude === void 0) return false;
+	const others = decorators.filter((decorator) => decorator !== exclude);
+	if (others.length > 0) ctx.report({
+		code: Codes.InconsistentOperation,
+		severity: "warning",
+		message: `${target} is excluded from the OpenAPI document (@ApiExclude): ${others.map((decorator) => `@${decorator.name}`).join(", ")} ${others.length > 1 ? "have" : "has"} no effect`,
+		location: exclude.location,
+		hints: ["Remove @ApiExclude to document it, or remove the other @Api* decorators"]
+	});
+	return true;
+}
+function tagsOf(ctx, decorators) {
+	const tags = [];
+	for (const decorator of decorators.filter((candidate) => candidate.identity === Ids.ApiTags)) for (const arg of decorator.args) if (typeof arg.value === "string" && arg.value.trim() !== "") tags.push(arg.value);
+	else invalidValue(ctx, arg, "a tag must be a non-empty string");
+	return [...new Set(tags)];
+}
+function invalidValue(ctx, arg, message, hints = []) {
+	ctx.report({
+		code: Codes.InvalidOpenApiDefinition,
+		severity: "error",
+		message,
+		location: arg.location,
+		hints
+	});
+}
+function checkDuplicateIds(ctx, operations) {
+	const byId = /* @__PURE__ */ new Map();
+	for (const operation of operations) {
+		const other = byId.get(operation.operationId);
+		if (other === void 0) {
+			byId.set(operation.operationId, operation);
+			continue;
+		}
+		ctx.report({
+			code: Codes.DuplicateOperationId,
+			severity: "error",
+			message: `Duplicate operation id "${operation.operationId}": ${other.label} and ${operation.label}`,
+			location: operation.location,
+			related: [{
+				message: "the other operation",
+				location: other.location
+			}],
+			hints: [`Rename one controller, or set an id: @ApiOperation({ operationId: '...' })`]
+		});
+	}
+}
+var OperationBuilder = class {
+	#input;
+	#ctx;
+	#source;
+	#label;
+	#location;
+	#doc;
+	#paramDocs;
+	#strict;
+	constructor(input, source) {
+		this.#input = input;
+		this.#ctx = input.ctx;
+		this.#source = source;
+		this.#label = `${source.httpMethod} ${source.route.fullPath} (${source.controller.displayName}.${source.route.handler})`;
+		this.#location = source.method?.location ?? source.route.location;
+		this.#doc = input.document.jsdoc ? source.method?.doc : void 0;
+		this.#paramDocs = /* @__PURE__ */ new Map();
+		for (const tag of this.#doc?.tags ?? []) {
+			if (tag.name !== "param") continue;
+			const match = /^(?:\{[^}]*\}\s*)?\[?([\w$]+)[^\s]*\s*(?:-\s*)?([\s\S]*)$/.exec(tag.text);
+			if (match?.[1] !== void 0 && match[2] !== void 0 && match[2].trim() !== "") this.#paramDocs.set(match[1], match[2].trim());
+		}
+		this.#strict = input.document.strict;
+	}
+	build() {
+		const { route, httpMethod, controller } = this.#source;
+		const method = httpMethod.toLowerCase();
+		const options = this.#apiOperation();
+		const operation = {};
+		const operationId = this.#operationId(options);
+		operation["operationId"] = operationId;
+		const summary = stringOption(options, "summary") ?? this.#doc?.summary;
+		const description = stringOption(options, "description") ?? this.#doc?.description;
+		if (summary !== void 0) operation["summary"] = summary;
+		if (description !== void 0) operation["description"] = description;
+		const methodTags = tagsOf(this.#ctx, this.#source.methodDecorators);
+		const tags = [.../* @__PURE__ */ new Set([...this.#source.classTags, ...methodTags])];
+		operation["tags"] = tags.length > 0 ? tags : [this.#source.defaultTag];
+		if (typeof options?.["deprecated"] === "boolean" ? options["deprecated"] : this.#doc?.tags.some((tag) => tag.name === "deprecated") === true) operation["deprecated"] = true;
+		if (isRecord(options?.["externalDocs"])) operation["externalDocs"] = toJson(options["externalDocs"]);
+		const parameters = this.#parameters();
+		if (parameters.length > 0) operation["parameters"] = parameters;
+		const body = this.#requestBody(httpMethod);
+		if (body !== void 0) operation["requestBody"] = body;
+		operation["responses"] = this.#responses(httpMethod);
+		const security = this.#security();
+		if (security !== void 0) operation["security"] = security;
+		if (isRecord(options?.["extensions"])) {
+			for (const [key, value] of Object.entries(options["extensions"])) if (key.startsWith("x-")) operation[key] = toJson(value);
+		}
+		if (route.fullPath.endsWith("/*")) operation["x-znight-wildcard"] = true;
+		return {
+			controller: controller.token,
+			handler: route.handler,
+			route: route.method,
+			method,
+			path: pathTemplate(route.fullPath),
+			operation,
+			operationId,
+			label: this.#label,
+			location: this.#location
+		};
+	}
+	#apiOperation() {
+		const arg = this.#source.methodDecorators.find((candidate) => candidate.identity === Ids.ApiOperation)?.args[0];
+		if (arg === void 0) return void 0;
+		if (!isRecord(arg.value)) {
+			invalidValue(this.#ctx, arg, `@ApiOperation takes { summary?, description?, operationId?, deprecated?, externalDocs?, extensions? }, received ${describe(arg.value)}`);
+			return;
+		}
+		const reserved = findReservedKey(arg.value);
+		if (reserved !== void 0) invalidValue(this.#ctx, arg, `"$znight" is a reserved key (${reserved})`);
+		for (const key of Object.keys(arg.value)) if (![
+			"summary",
+			"description",
+			"operationId",
+			"deprecated",
+			"externalDocs",
+			"extensions"
+		].includes(key)) invalidValue(this.#ctx, arg, `@ApiOperation: unknown option "${key}"`);
+		const extensions = arg.value["extensions"];
+		if (isRecord(extensions)) {
+			for (const key of Object.keys(extensions)) if (!key.startsWith("x-")) invalidValue(this.#ctx, arg, `@ApiOperation: the extension "${key}" must start with "x-"`);
+		}
+		return arg.value;
+	}
+	#operationId(options) {
+		const { controller, route, httpMethod } = this.#source;
+		const explicit = options?.["operationId"];
+		if (explicit !== void 0) {
+			if (typeof explicit !== "string" || !OPERATION_ID.test(explicit)) {
+				const decorator = this.#source.methodDecorators.find((candidate) => candidate.identity === Ids.ApiOperation);
+				invalidValue(this.#ctx, decorator ?? { location: this.#location }, `Invalid operation id ${describe(explicit)}: it must match ${String(OPERATION_ID)}`);
+			} else return route.method === "ALL" ? `${explicit}.${httpMethod.toLowerCase()}` : explicit;
+		}
+		const base = controller.displayName.replace(/Controller$/, "") || controller.displayName;
+		let id;
+		switch (this.#input.document.operationIds) {
+			case "handler":
+				id = route.handler;
+				break;
+			case "Controller_handler":
+				id = `${controller.displayName}_${route.handler}`;
+				break;
+			default: id = `${base.charAt(0).toLowerCase()}${base.slice(1)}.${route.handler}`;
+		}
+		if (route.method === "ALL") id = `${id}.${httpMethod.toLowerCase()}`;
+		if (!OPERATION_ID.test(id)) id = id.replace(/[^\w.-]/g, "_").replace(/^[^A-Za-z_]/, "_");
+		return id;
+	}
+	#use(part, io, location) {
+		return {
+			io,
+			operation: this.#label,
+			part,
+			location: location ?? this.#location
+		};
+	}
+	#paramInfo(data) {
+		return this.#source.method?.params.find((param) => param.index === data.index);
+	}
+	#paramDoc(data) {
+		return this.#paramDocs.get(this.#paramInfo(data)?.name ?? data.name);
+	}
+	#parameters() {
+		const { route } = this.#source;
+		const parameters = [];
+		const declared = /* @__PURE__ */ new Set();
+		const params = route.params;
+		const wholePath = params.find((param) => param.source === "param" && param.key === void 0 && param.schema !== void 0);
+		if (wholePath?.schema === void 0) for (const segment of route.fullPath.split("/")) {
+			if (!segment.startsWith(":") && segment !== "*") continue;
+			const key = segment === "*" ? "*" : segment.slice(1);
+			const data = params.find((param) => param.source === "param" && param.key === key);
+			const parameter = {
+				name: key === "*" ? wildcardName(route.fullPath) : key,
+				in: "path"
+			};
+			const doc = data === void 0 ? void 0 : this.#paramDoc(data);
+			if (doc !== void 0) parameter["description"] = doc;
+			else if (key === "*") parameter["description"] = "The rest of the path, `/` included";
+			parameter["required"] = true;
+			parameter["schema"] = data === void 0 ? { type: "string" } : this.#paramSchema(data, `path parameter "${key}"`);
+			if (key === "*") parameter["x-znight-wildcard"] = true;
+			parameters.push(parameter);
+			declared.add(`path ${parameter["name"]}`);
+		}
+		else {
+			const name = this.#input.slots.use(wholePath.schema, "input")?.name;
+			if (name !== void 0) parameters.push(placeholder("path", name));
+		}
+		for (const data of params) if (data.source === "query") this.#signatureParameter(data, "query", parameters, declared);
+		else if (data.source === "headers") this.#signatureParameter(data, "header", parameters, declared);
+		else if (data.source === "cookie" || data.source === "signedCookie") this.#signatureParameter(data, "cookie", parameters, declared);
+		const decorated = [...this.#source.classDecorators.filter((decorator) => decorator.identity === Ids.ApiHeader), ...this.#source.methodDecorators.filter((decorator) => decorator.identity === Ids.ApiQuery || decorator.identity === Ids.ApiHeader)];
+		for (const decorator of decorated) {
+			const parameter = this.#decoratedParameter(decorator, declared);
+			if (parameter !== void 0) parameters.push(parameter);
+		}
+		return parameters;
+	}
+	#signatureParameter(data, location, parameters, declared) {
+		if (data.key === void 0) {
+			if (data.schema !== void 0) {
+				const name = this.#input.slots.use(data.schema, "input")?.name;
+				if (name !== void 0) parameters.push(placeholder(location, name));
+				return;
+			}
+			const info = this.#paramInfo(data);
+			if (info === void 0 || location !== "query") return;
+			const result = this.#input.schemas.shape({ parameter: info });
+			const use = this.#use(`the ${location} parameters`, "input", info.typeLocation);
+			this.#input.schemas.register(result, use);
+			const object = this.#objectProperties(result.root);
+			for (const property of object ?? []) {
+				const parameter = {
+					name: property.name,
+					in: location
+				};
+				if (property.description !== void 0) parameter["description"] = property.description;
+				if (!property.optional) parameter["required"] = true;
+				parameter["schema"] = this.#input.schemas.convert(property.shape, use, property.name);
+				if (property.shape.kind === "array") {
+					parameter["style"] = "form";
+					parameter["explode"] = true;
+				}
+				parameters.push(parameter);
+				declared.add(`${location} ${property.name}`);
+			}
+			return;
+		}
+		if (location === "header" && IGNORED_HEADERS.has(data.key)) {
+			this.#ctx.report({
+				code: Codes.InconsistentOperation,
+				severity: "warning",
+				message: `The "${data.key}" header of ${this.#label} is not documented as a parameter: OpenAPI ignores Accept, Content-Type and Authorization parameters`,
+				location: data.location,
+				hints: ["Describe credentials with a security scheme (securityScheme()) and @ApiSecurity or decisions"]
+			});
+			return;
+		}
+		const parameter = {
+			name: data.key,
+			in: location
+		};
+		const doc = this.#paramDoc(data);
+		if (doc !== void 0) parameter["description"] = doc;
+		if (!data.optional) parameter["required"] = true;
+		parameter["schema"] = this.#paramSchema(data, `${location} parameter "${data.key}"`);
+		if (location === "query" && isArrayPlan(data.coercion?.plan)) {
+			parameter["style"] = "form";
+			parameter["explode"] = true;
+		}
+		parameters.push(parameter);
+		declared.add(`${location} ${data.key}`);
+	}
+	#objectProperties(shape) {
+		if (shape.kind === "named") {
+			const named = this.#input.schemas.named(shape.key);
+			return named === void 0 ? void 0 : this.#objectProperties(named.shape);
+		}
+		if (shape.kind !== "object") return void 0;
+		return shape.properties.map((property) => ({
+			name: property.name,
+			shape: property.shape,
+			optional: property.optional,
+			description: property.doc?.text === "" ? void 0 : property.doc?.text
+		}));
+	}
+	#paramSchema(data, part) {
+		if (data.schema !== void 0) return this.#input.slots.use(data.schema, "input") ?? {};
+		const schema = data.coercion === void 0 ? {} : { ...planSchema(data.coercion.plan) };
+		if (data.defaultValue !== void 0) {
+			const value = toJson(data.defaultValue);
+			if (value !== void 0) schema["default"] = value;
+		}
+		return schema;
+	}
+	#decoratedParameter(decorator, declared) {
+		const location = decorator.identity === Ids.ApiQuery ? "query" : "header";
+		const [nameArg, optionsArg] = decorator.args;
+		const name = nameArg?.value;
+		if (typeof name !== "string" || name === "") {
+			invalidValue(this.#ctx, nameArg ?? decorator, `@${decorator.name} needs a parameter name`);
+			return;
+		}
+		const key = location === "header" ? name.toLowerCase() : name;
+		if (location === "header" && !HEADER_NAME.test(name)) {
+			invalidValue(this.#ctx, nameArg ?? decorator, `Invalid header name ${JSON.stringify(name)}`);
+			return;
+		}
+		if (location === "header" && IGNORED_HEADERS.has(key)) {
+			this.#ctx.report({
+				code: Codes.InconsistentOperation,
+				severity: "error",
+				message: `@ApiHeader('${name}'): OpenAPI ignores Accept, Content-Type and Authorization parameters`,
+				location: decorator.location,
+				hints: ["Describe credentials with a security scheme: securityScheme() and @ApiSecurity"]
+			});
+			return;
+		}
+		if (declared.has(`${location} ${key}`)) {
+			this.#ctx.report({
+				code: Codes.InconsistentOperation,
+				severity: "error",
+				message: `@${decorator.name}('${name}') documents the ${location} parameter "${key}" of ${this.#label}, which the signature already reads`,
+				location: decorator.location,
+				hints: [`Remove @${decorator.name}: the parameter is documented from the signature`]
+			});
+			return;
+		}
+		declared.add(`${location} ${key}`);
+		const options = optionsArg?.value;
+		if (options !== void 0 && !isRecord(options)) invalidValue(this.#ctx, optionsArg ?? decorator, `@${decorator.name} options must be { description?, required?, deprecated?, example? }`);
+		const record = isRecord(options) ? options : {};
+		for (const option of Object.keys(record)) if (![
+			"description",
+			"required",
+			"deprecated",
+			"example"
+		].includes(option)) invalidValue(this.#ctx, optionsArg ?? decorator, `@${decorator.name}: unknown option "${option}"`);
+		const parameter = {
+			name: key,
+			in: location
+		};
+		if (typeof record["description"] === "string") parameter["description"] = record["description"];
+		if (record["required"] === true) parameter["required"] = true;
+		if (record["deprecated"] === true) parameter["deprecated"] = true;
+		if (decorator.typeArgs.length > 0) {
+			const result = this.#input.schemas.shape({
+				decorator,
+				typeArgument: 0
+			});
+			parameter["schema"] = this.#input.schemas.fromResult(result, this.#use(`the ${location} parameter "${key}"`, "input", decorator.location));
+		} else parameter["schema"] = { type: "string" };
+		if (record["example"] !== void 0) parameter["example"] = toJson(record["example"]);
+		return parameter;
+	}
+	#requestBody(httpMethod) {
+		const { route } = this.#source;
+		const body = route.params.find((param) => param.source === "body");
+		const uploads = route.params.filter((param) => param.upload !== void 0);
+		const apiBody = this.#source.methodDecorators.find((decorator) => decorator.identity === Ids.ApiBody);
+		if (apiBody !== void 0 && (httpMethod === "GET" || httpMethod === "HEAD")) this.#ctx.report({
+			code: Codes.InconsistentOperation,
+			severity: "warning",
+			message: `@ApiBody on ${this.#label}: ${httpMethod} requests have no body in OpenAPI tools`,
+			location: apiBody.location,
+			hints: ["Use another method, or remove @ApiBody"]
+		});
+		if (apiBody !== void 0 && (body?.schema !== void 0 || route.bodySchema !== void 0)) {
+			this.#ctx.report({
+				code: Codes.InconsistentOperation,
+				severity: "error",
+				message: `@ApiBody on ${this.#label}, whose body is already documented by its schema`,
+				location: apiBody.location,
+				hints: ["Remove @ApiBody: the body schema documents the request"]
+			});
+			return this.#bodyFromSignature(body, uploads);
+		}
+		if (apiBody !== void 0 && uploads.length === 0) return this.#declaredBody(apiBody, body);
+		return this.#bodyFromSignature(body, uploads);
+	}
+	#bodyFromSignature(body, uploads) {
+		const { route } = this.#source;
+		if (uploads.length > 0) return this.#multipart(body, uploads);
+		if (body !== void 0) {
+			const request = {};
+			const doc = this.#paramDoc(body);
+			if (doc !== void 0) request["description"] = doc;
+			let content;
+			if (body.schema === void 0) {
+				const info = this.#paramInfo(body);
+				const result = info === void 0 ? void 0 : this.#input.schemas.shape({ parameter: info });
+				const root = result?.root;
+				if (result === void 0 || root === void 0) content = { "application/json": { schema: {} } };
+				else if (root.kind === "string") content = { "text/plain": { schema: { type: "string" } } };
+				else if (root.kind === "binary") content = { "application/octet-stream": {} };
+				else content = { "application/json": { schema: this.#input.schemas.fromResult(result, this.#use("the request body", "input", info?.typeLocation)) } };
+			} else content = { "application/json": { schema: this.#input.slots.use(body.schema, "input") ?? {} } };
+			request["content"] = content;
+			if (!body.optional) request["required"] = true;
+			return request;
+		}
+		if (route.bodySchema !== void 0) return {
+			content: { "application/json": { schema: this.#input.slots.use(route.bodySchema, "input") ?? {} } },
+			required: true
+		};
+	}
+	#multipart(form, uploads) {
+		const properties = {};
+		const required = [];
+		const encoding = {};
+		let additional;
+		for (const param of uploads) {
+			const upload = param.upload;
+			const file = {
+				type: "string",
+				contentMediaType: "application/octet-stream"
+			};
+			const doc = this.#paramDoc(param);
+			const size = upload.maxSize === void 0 || upload.maxSize === Number.POSITIVE_INFINITY ? void 0 : upload.maxSize;
+			const descriptions = [doc, size === void 0 ? void 0 : `At most ${formatSize(size)}`].filter((text) => text !== void 0);
+			if (descriptions.length > 0) file["description"] = descriptions.join(". ");
+			if (size !== void 0) file["x-znight-max-size"] = size;
+			const schema = upload.multiple ? {
+				type: "array",
+				items: file,
+				...upload.maxFiles === void 0 || upload.maxFiles === Number.POSITIVE_INFINITY ? {} : { maxItems: upload.maxFiles }
+			} : file;
+			if (upload.field === void 0) {
+				additional = schema;
+				continue;
+			}
+			properties[upload.field] = schema;
+			if (upload.required) required.push(upload.field);
+			if (upload.mimeTypes !== void 0 && upload.mimeTypes.length > 0) encoding[upload.field] = { contentType: upload.mimeTypes.join(", ") };
+		}
+		const files = { type: "object" };
+		if (Object.keys(properties).length > 0) files["properties"] = properties;
+		if (required.length > 0) files["required"] = required.sort(compareStrings);
+		if (additional !== void 0) files["additionalProperties"] = additional;
+		const textFields = form?.schema === void 0 ? void 0 : this.#input.slots.use(form.schema, "input");
+		const media = { schema: textFields === void 0 ? files : { allOf: [textFields, files] } };
+		if (Object.keys(encoding).length > 0) media["encoding"] = encoding;
+		const request = { content: { "multipart/form-data": media } };
+		if (required.length > 0 || form !== void 0 && !form.optional) request["required"] = true;
+		return request;
+	}
+	#declaredBody(decorator, body) {
+		const arg = decorator.args[0];
+		const options = arg?.value;
+		if (options !== void 0 && !isRecord(options)) {
+			invalidValue(this.#ctx, arg ?? decorator, "@ApiBody options must be { description?, required?, contentType?, schema? }");
+			return;
+		}
+		const record = isRecord(options) ? options : {};
+		for (const key of Object.keys(record)) if (![
+			"description",
+			"required",
+			"contentType",
+			"schema"
+		].includes(key)) invalidValue(this.#ctx, arg ?? decorator, `@ApiBody: unknown option "${key}"`);
+		const contentTypes = this.#mediaTypes(record["contentType"], arg ?? decorator) ?? ["application/json"];
+		let schema;
+		const schemaOption = record["schema"];
+		if (isRef(schemaOption)) schema = this.#input.slots.use(schemaOption, "input");
+		else if (schemaOption !== void 0) invalidValue(this.#ctx, arg ?? decorator, "@ApiBody schema must be a Standard Schema (an exported schema)");
+		else if (decorator.typeArgs.length > 0) {
+			const result = this.#input.schemas.shape({
+				decorator,
+				typeArgument: 0
+			});
+			schema = this.#input.schemas.fromResult(result, this.#use("the request body", "input", decorator.location));
+		}
+		const content = {};
+		for (const type of contentTypes) content[type] = schema === void 0 ? defaultMedia(type) : { schema };
+		const request = {};
+		if (typeof record["description"] === "string") request["description"] = record["description"];
+		request["content"] = content;
+		if (record["required"] !== false) request["required"] = true;
+		return request;
+	}
+	#mediaTypes(value, where) {
+		if (value === void 0) return void 0;
+		let list;
+		if (typeof value === "string") list = [value];
+		else if (Array.isArray(value)) list = value;
+		if (list === void 0 || list.length === 0 || list.some((item) => typeof item !== "string" || !MEDIA_TYPE.test(item))) {
+			invalidValue(this.#ctx, where, `Invalid media type ${describe(value)}: expected "type/subtype" or a list of them`);
+			return;
+		}
+		return list;
+	}
+	#responses(httpMethod) {
+		const { route, method } = this.#source;
+		const errors = this.#input.document.errors;
+		const declared = this.#source.methodDecorators.filter((decorator) => decorator.identity === Ids.ApiResponse);
+		const declaredStatuses = declared.map((decorator) => decorator.args[0]?.value).map((status) => typeof status === "number" ? String(status) : status);
+		const success = this.#success(httpMethod);
+		const responses = /* @__PURE__ */ new Map();
+		const covered = declaredStatuses.includes(String(success.status)) || declaredStatuses.includes("2XX") || success.dynamic && declaredStatuses.some((status) => typeof status === "string" && /^2\d\d$/.test(status));
+		if (success.problem !== void 0 && !covered) this.#ctx.report({
+			code: Codes.UndocumentedResponse,
+			severity: this.#strict ? "error" : "warning",
+			message: `The ${success.status} response of ${this.#label} cannot be documented: ${success.problem}`,
+			location: success.location ?? this.#location,
+			hints: success.hints
+		});
+		const returns = this.#doc?.tags.find((tag) => tag.name === "returns" || tag.name === "return")?.text;
+		if (success.problem === void 0 || !covered) {
+			const headers = {};
+			for (const [name, value] of route.headers) headers[name] = {
+				schema: { type: "string" },
+				example: value
+			};
+			responses.set(String(success.status), {
+				description: returns !== void 0 && returns !== "" ? returns : void 0,
+				headers,
+				content: success.content
+			});
+			if (success.empty !== void 0) responses.set(String(success.empty), {
+				description: void 0,
+				headers: { ...headers },
+				content: void 0
+			});
+		}
+		for (const decorator of declared) this.#declaredResponse(decorator, responses, success);
+		const result = {};
+		const reads = route.params.some((param) => param.source === "body" || param.upload !== void 0) || route.bodySchema !== void 0;
+		const validates = reads || route.params.some((param) => param.schema !== void 0 || param.coercion !== void 0 && param.coercion.plan.kind !== "raw");
+		const uploads = route.params.some((param) => param.upload !== void 0);
+		if (errors !== false) {
+			const standard = (status, name) => {
+				if (!responses.has(status)) result[status] = { $ref: `#/components/responses/${name}` };
+			};
+			if (validates) standard("400", ERROR_RESPONSES.badRequest);
+			if (reads) standard("413", ERROR_RESPONSES.payloadTooLarge);
+			if (uploads) standard("415", ERROR_RESPONSES.unsupportedMediaType);
+		}
+		for (const [status, draft] of responses) {
+			const response = { description: draft.description ?? reasonPhrase(status) };
+			if (Object.keys(draft.headers).length > 0) response["headers"] = draft.headers;
+			let content = draft.content;
+			if (content === void 0 && errors !== false && /^[45]/.test(status)) {
+				const schema = errors.schema === void 0 ? { $ref: schemaRef(ERROR_COMPONENTS.body) } : this.#input.slots.use(errors.schema, "output") ?? {};
+				content = { [errors.contentType]: { schema } };
+			}
+			if (content !== void 0) response["content"] = content;
+			result[status] = response;
+		}
+		const sorted = {};
+		for (const status of Object.keys(result).sort(compareStatuses)) sorted[status] = result[status];
+		return sorted;
+	}
+	#success(httpMethod) {
+		const { route, method } = this.#source;
+		const example = exampleBodyType(this.#source.controller.displayName);
+		const post = httpMethod === "POST";
+		const statusFor = (empty) => {
+			if (route.status !== void 0) return route.status;
+			if (post) return 201;
+			return empty ? 204 : 200;
+		};
+		const undocumentable = (problem, hints, dynamic = false) => ({
+			status: statusFor(false),
+			dynamic,
+			empty: void 0,
+			content: void 0,
+			problem,
+			hints,
+			location: method?.location
+		});
+		if (route.sse !== void 0) return this.#sse();
+		if (route.rawResponse) return undocumentable("the handler writes the response itself (@Res())", [`Declare it: @ApiResponse<${example}>(${statusFor(false)})`], true);
+		if (method?.returnType === void 0) return undocumentable("the handler has no return type annotation", [`Annotate the return type with the body type: ${handlerKey(route.handler)}(): ${method?.async === true ? `Promise<${example}>` : example}`, `Or declare it: @ApiResponse<${example}>(${statusFor(false)})`]);
+		const result = this.#input.schemas.shape({ returnOf: method });
+		const use = this.#use("the response", "output");
+		this.#input.schemas.register(result, use);
+		let dynamic = false;
+		let returnsUndefined = false;
+		const bodies = [];
+		for (const member of unionMembers(result.root)) if (member.kind === "reference" && member.identity === HttpIds.HttpResponse) {
+			dynamic = true;
+			const body = member.typeArgs[0];
+			if (member.explicitTypeArgs === 0 || body === void 0) return undocumentable("HttpResponse has no body type", [`Give the body type: Promise<HttpResponse<${example}>>`, `Or declare it: @ApiResponse<${example}>(${statusFor(false)})`], true);
+			bodies.push(...unionMembers(body));
+		} else {
+			if (member.kind === "undefined") returnsUndefined = true;
+			bodies.push(member);
+		}
+		const defined = distinct(bodies.filter((member) => member.kind !== "undefined" && member.kind !== "never"));
+		if (defined.some((member) => member.kind === "reference" && member.identity === "globalThis#Response")) return undocumentable("a Web Response has no body type", [`Declare it: @ApiResponse<${example}>(${statusFor(false)})`], true);
+		if (defined.some((member) => member.kind === "unknown")) return undocumentable(`the return type is ${method.returnType.kind === "primitive" ? method.returnType.name : "unknown"}`, ["Give a precise return type", `Or declare it: @ApiResponse<${example}>(${statusFor(false)})`], dynamic);
+		if (defined.length === 0) return {
+			status: statusFor(true),
+			dynamic,
+			empty: void 0,
+			content: void 0,
+			problem: void 0,
+			hints: [],
+			location: void 0
+		};
+		const events = defined.filter((member) => member.kind === "reference" && member.identity === HttpIds.SseBody);
+		if (events.length > 0) {
+			if (events.length < defined.length) return undocumentable("the handler returns an event stream or another body", [`Declare the responses: @ApiResponse(${route.status ?? 200}, { contentType: 'text/event-stream' })`], true);
+			return {
+				status: route.status ?? 200,
+				dynamic: true,
+				empty: void 0,
+				content: httpMethod === "HEAD" ? void 0 : { "text/event-stream": { schema: { type: "string" } } },
+				problem: void 0,
+				hints: [],
+				location: void 0
+			};
+		}
+		const status = statusFor(false);
+		let content = this.#successContent(defined, use);
+		if (content !== void 0 && isBodylessStatus(status)) {
+			this.#ctx.report({
+				code: Codes.InconsistentOperation,
+				severity: "error",
+				message: `${this.#label} returns a body, but its status is always ${status} (@HttpCode(${status})): ${status} responses have none, the body is never sent`,
+				location: method.location,
+				hints: ["Return nothing (void), or use another status"]
+			});
+			content = void 0;
+		}
+		return {
+			status,
+			dynamic,
+			empty: returnsUndefined && route.status === void 0 && !post && status !== 204 ? 204 : void 0,
+			content: httpMethod === "HEAD" ? void 0 : content,
+			problem: void 0,
+			hints: [],
+			location: void 0
+		};
+	}
+	/** Content of the success response: media types of the serialiser (§9.1 of the architecture). */
+	#successContent(members, use) {
+		const single = members.length === 1 ? members[0] : void 0;
+		if (single !== void 0) {
+			if (single.kind === "binary" || single.kind === "reference" && single.identity === HttpIds.FileBody) return { "application/octet-stream": {} };
+			if (single.kind === "reference" && single.identity === "globalThis#AsyncIterable") {
+				const event = single.typeArgs[0];
+				const data = event?.kind === "reference" && event.identity === HttpIds.SseEvent ? event.typeArgs[0] : event;
+				const media = { schema: { type: "string" } };
+				if (data !== void 0) media["x-znight-event-schema"] = this.#input.schemas.convert(data, use, "");
+				return { "text/event-stream": media };
+			}
+		}
+		const text = [];
+		const json = [];
+		for (const member of members) this.#splitText(member, text, json, /* @__PURE__ */ new Set());
+		const schemaOf = (shapes) => this.#input.schemas.convert(shapes.length === 1 ? shapes[0] : {
+			kind: "union",
+			members: shapes
+		}, use, "");
+		const content = {};
+		if (json.length > 0) content["application/json"] = { schema: schemaOf(json) };
+		if (text.length > 0) content["text/plain"] = { schema: schemaOf(text) };
+		return content;
+	}
+	/**
+	* Sorts the members of a body by the media type the serialiser gives them: strings (string, string
+	* literals, string enums) are text, the rest JSON. A named declaration stays whole when all its
+	* members go to one side.
+	*/
+	#splitText(shape, text, json, seen) {
+		const kind = this.#textKind(shape, new Set(seen));
+		if (kind === "text") text.push(shape);
+		else if (kind === "json") json.push(shape);
+		else if (shape.kind === "union") for (const member of shape.members) this.#splitText(member, text, json, seen);
+		else if (shape.kind === "named") {
+			const named = this.#input.schemas.named(shape.key);
+			if (named === void 0 || seen.has(shape.key)) json.push(shape);
+			else this.#splitText(named.shape, text, json, /* @__PURE__ */ new Set([...seen, shape.key]));
+		} else json.push(shape);
+	}
+	#textKind(shape, seen) {
+		switch (shape.kind) {
+			case "string": return "text";
+			case "literal": return typeof shape.value === "string" ? "text" : "json";
+			case "union": {
+				const kinds = new Set(shape.members.map((member) => this.#textKind(member, seen)));
+				return kinds.size === 1 ? [...kinds][0] : "mixed";
+			}
+			case "intersection": return shape.members.some((member) => this.#textKind(member, seen) === "text") ? "text" : "json";
+			case "named": {
+				const named = this.#input.schemas.named(shape.key);
+				if (named === void 0 || seen.has(shape.key)) return "json";
+				seen.add(shape.key);
+				return this.#textKind(named.shape, seen);
+			}
+			default: return "json";
+		}
+	}
+	/** `@Sse` routes: a 200 event stream; the type of the events' `data` when the return type tells it. */
+	#sse() {
+		const { method } = this.#source;
+		const media = { schema: { type: "string" } };
+		if (method?.returnType !== void 0) {
+			const result = this.#input.schemas.shape({ returnOf: method });
+			const use = this.#use("the events", "output");
+			this.#input.schemas.register(result, use);
+			const data = eventData(result.root);
+			if (data !== void 0) media["x-znight-event-schema"] = this.#input.schemas.convert(data, use, "");
+		}
+		return {
+			status: 200,
+			dynamic: true,
+			empty: void 0,
+			content: { "text/event-stream": media },
+			problem: void 0,
+			hints: [],
+			location: void 0
+		};
+	}
+	#declaredResponse(decorator, responses, success) {
+		const [statusArg, optionsArg] = decorator.args;
+		const raw = statusArg?.value;
+		const status = typeof raw === "number" ? String(raw) : raw;
+		if (typeof status !== "string" || !isResponseStatus(status)) {
+			invalidValue(this.#ctx, statusArg ?? decorator, `Invalid response status ${describe(raw)}: expected a code (100-599), "2XX"-like or "default"`);
+			return;
+		}
+		const options = optionsArg?.value;
+		if (options !== void 0 && !isRecord(options)) {
+			invalidValue(this.#ctx, optionsArg ?? decorator, "@ApiResponse options must be { description?, schema?, contentType?, headers?, example? }");
+			return;
+		}
+		const record = isRecord(options) ? options : {};
+		for (const key of Object.keys(record)) if (![
+			"description",
+			"schema",
+			"contentType",
+			"headers",
+			"example"
+		].includes(key)) invalidValue(this.#ctx, optionsArg ?? decorator, `@ApiResponse: unknown option "${key}"`);
+		const reserved = findReservedKey(record);
+		if (reserved !== void 0) invalidValue(this.#ctx, optionsArg ?? decorator, `"$znight" is a reserved key (${reserved})`);
+		const code = Number(status);
+		if (Number.isInteger(code) && code >= 200 && code < 300 && code !== success.status && code !== success.empty) {
+			if (this.#source.route.status !== void 0 || !success.dynamic) {
+				this.#ctx.report({
+					code: Codes.InconsistentOperation,
+					severity: "error",
+					message: `@ApiResponse(${status}) on ${this.#label}, whose success status is always ${success.status}`,
+					location: decorator.location,
+					hints: [this.#source.route.status === void 0 ? `Return an HttpResponse to choose the status, or document ${success.status}` : `@HttpCode(${this.#source.route.status}) sets the status: document ${this.#source.route.status}`]
+				});
+				return;
+			}
+		}
+		let schema;
+		const schemaOption = record["schema"];
+		if (isRef(schemaOption)) schema = this.#input.slots.use(schemaOption, "output");
+		else if (schemaOption !== void 0) invalidValue(this.#ctx, optionsArg ?? decorator, "@ApiResponse schema must be a Standard Schema (an exported schema)");
+		else if (decorator.typeArgs.length > 0) {
+			const result = this.#input.schemas.shape({
+				decorator,
+				typeArgument: 0
+			});
+			schema = this.#input.schemas.fromResult(result, this.#use(`the ${status} response`, "output", decorator.location));
+		}
+		if (schema !== void 0 && (status === "204" || status === "304")) {
+			this.#ctx.report({
+				code: Codes.InconsistentOperation,
+				severity: "error",
+				message: `@ApiResponse(${status}) on ${this.#label} declares a body: ${status} responses have none`,
+				location: decorator.location,
+				hints: ["Remove the body type, or use another status"]
+			});
+			schema = void 0;
+		}
+		const contentTypes = this.#mediaTypes(record["contentType"], optionsArg ?? decorator);
+		const draft = responses.get(status) ?? {
+			description: void 0,
+			headers: {},
+			content: void 0
+		};
+		if (typeof record["description"] === "string") draft.description = record["description"];
+		const headers = record["headers"];
+		if (headers !== void 0) {
+			if (isRecord(headers)) for (const [name, header] of Object.entries(headers)) {
+				if (!HEADER_NAME.test(name)) {
+					invalidValue(this.#ctx, optionsArg ?? decorator, `Invalid header name ${JSON.stringify(name)}`);
+					continue;
+				}
+				const json = toJson(header);
+				const object = isRecord(json) ? json : {};
+				draft.headers[name.toLowerCase()] = {
+					...draft.headers[name.toLowerCase()],
+					...object,
+					schema: object["schema"] ?? { type: "string" }
+				};
+			}
+			else invalidValue(this.#ctx, optionsArg ?? decorator, "@ApiResponse headers must be { [name]: { description?, schema?, ... } }");
+		}
+		const example = record["example"] === void 0 ? void 0 : toJson(record["example"]);
+		if (schema !== void 0 || contentTypes !== void 0) {
+			const previous = draft.content === void 0 ? void 0 : Object.values(draft.content)[0];
+			const types = contentTypes ?? (schema === void 0 ? [] : ["application/json"]);
+			const content = {};
+			for (const type of types) {
+				const media = {};
+				const mediaSchema = schema ?? previous?.["schema"];
+				if (mediaSchema !== void 0) media["schema"] = mediaSchema;
+				if (example !== void 0) media["example"] = example;
+				content[type] = media;
+			}
+			draft.content = content;
+		} else if (example !== void 0 && draft.content !== void 0) for (const media of Object.values(draft.content)) media["example"] = example;
+		responses.set(status, draft);
+	}
+	#security() {
+		const { schemes } = this.#input;
+		for (const decorators of [this.#source.methodDecorators, this.#source.classDecorators]) {
+			const decorator = decorators.find((candidate) => candidate.identity === Ids.ApiSecurity);
+			if (decorator === void 0) continue;
+			const requirements = [];
+			for (const arg of decorator.args) {
+				const requirement = schemes.requirement(arg.ref ?? arg.value, arg.location);
+				if (requirement !== void 0) requirements.push(requirement);
+			}
+			return schemes.objects(requirements);
+		}
+		const decisions = this.#input.document.decisions;
+		if (decisions.length === 0) return void 0;
+		const { route, controller } = this.#source;
+		const routeGroups = new Set(route.meta.map((entry) => entry.group));
+		const inherited = controller.meta.filter((entry) => !routeGroups.has(entry.group));
+		for (const entries of [route.meta, inherited]) for (const decision of decisions) {
+			const entry = entries.find((candidate) => candidate.identity === decision.identity);
+			if (entry === void 0) continue;
+			decision.used = true;
+			return this.#decisionSecurity(decision, entry);
+		}
+	}
+	#decisionSecurity(decision, entry) {
+		const { schemes } = this.#input;
+		if (!decision.scopesFromValue) return schemes.objects(decision.security);
+		const value = entry.value;
+		if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+			this.#ctx.report({
+				code: Codes.InvalidSecurityRequirement,
+				severity: "error",
+				message: `The decision on ${decision.text} takes its scopes from the decorator value, but @${entry.decorator}(...) on ${this.#label} is not a static string array`,
+				location: entry.location,
+				hints: [`Write the scopes literally: @${entry.decorator}(['admin'])`]
+			});
+			return schemes.objects(decision.security);
+		}
+		const scopes = value;
+		for (const requirement of decision.security) for (const { scheme } of requirement) {
+			if (!scheme.scoped) {
+				this.#ctx.report({
+					code: Codes.InvalidSecurityRequirement,
+					severity: "error",
+					message: `The decision on ${decision.text} gives scopes to "${scheme.name}" (${String(scheme.definition.type)}): scopes are only allowed on oauth2 and openIdConnect schemes`,
+					location: decision.location,
+					hints: ["Remove scopes: 'value', or use an oauth2 scheme"]
+				});
+				return schemes.objects(decision.security);
+			}
+			const unknown = scheme.scopes === void 0 ? [] : scopes.filter((scope) => !scheme.scopes?.has(scope));
+			if (unknown.length > 0) this.#ctx.report({
+				code: Codes.InvalidSecurityRequirement,
+				severity: "error",
+				message: `@${entry.decorator}(${JSON.stringify(scopes)}) on ${this.#label} uses ${unknown.length > 1 ? "scopes" : "a scope"} that "${scheme.name}" does not declare: ${unknown.join(", ")}`,
+				location: entry.location,
+				related: [{
+					message: "the security scheme",
+					location: scheme.location
+				}],
+				hints: [`Declare the scope in the flows of ${scheme.name}, or fix the decorator value`]
+			});
+		}
+		return schemes.objects(decision.security, scopes);
+	}
+};
+/** A media type without declared schema: text is a string, bytes have no schema, anything else is any value. */
+function defaultMedia(type) {
+	if (type.startsWith("text/")) return { schema: { type: "string" } };
+	return type === "application/octet-stream" ? {} : { schema: {} };
+}
+function stringOption(options, key) {
+	const value = options?.[key];
+	return typeof value === "string" ? value : void 0;
+}
+function placeholder(location, name) {
+	return {
+		$znight: "parameters",
+		in: location,
+		name,
+		io: "input"
+	};
+}
+function isArrayPlan(plan) {
+	if (plan === void 0) return false;
+	if (plan.kind === "optional") return isArrayPlan(plan.item);
+	return plan.kind === "array";
+}
+/** The members of a union (the shape itself otherwise). */
+function unionMembers(shape) {
+	return shape.kind === "union" ? shape.members : [shape];
+}
+/** The shapes without repetitions (`Book | HttpResponse<Book>` documents `Book` once). */
+function distinct(shapes) {
+	const seen = /* @__PURE__ */ new Set();
+	return shapes.filter((shape) => {
+		let key;
+		try {
+			key = JSON.stringify(shape);
+		} catch {
+			return true;
+		}
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	});
+}
+/** Statuses whose responses have no body: the serialiser drops it (204, 304, 1xx). */
+function isBodylessStatus(status) {
+	return status === 204 || status === 304 || status >= 100 && status < 200;
+}
+/** The `T` of `SseEvent<T>` found in a stream type (`AsyncIterable<SseEvent<T>> | HttpResponse`). */
+function eventData(shape) {
+	if (shape.kind === "reference") {
+		if (shape.identity === HttpIds.SseEvent) return shape.typeArgs[0];
+		for (const arg of shape.typeArgs) {
+			const found = eventData(arg);
+			if (found !== void 0) return found;
+		}
+		return;
+	}
+	if (shape.kind === "union") for (const member of shape.members) {
+		const found = eventData(member);
+		if (found !== void 0) return found;
+	}
+}
+/** JSON Schema of a coercion plan (§5.4.2). */
+function planSchema(plan) {
+	switch (plan.kind) {
+		case "string":
+		case "number":
+		case "integer":
+		case "boolean": return { type: plan.kind };
+		case "bigint": return {
+			type: "string",
+			pattern: "^-?[0-9]+$"
+		};
+		case "date": return {
+			type: "string",
+			format: "date-time"
+		};
+		case "enum": {
+			const types = [...new Set(plan.values.map((value) => typeof value))];
+			return types.length === 1 ? {
+				type: types[0],
+				enum: [...plan.values]
+			} : { enum: [...plan.values] };
+		}
+		case "array": return {
+			type: "array",
+			items: planSchema(plan.item)
+		};
+		case "optional": return planSchema(plan.item);
+		case "raw": return {};
+	}
+}
+/** `2 MiB`, `512 KiB`, `1000 bytes`. */
+function formatSize(bytes) {
+	const units = [
+		"GiB",
+		"MiB",
+		"KiB"
+	];
+	const factors = [
+		1024 ** 3,
+		1024 ** 2,
+		1024
+	];
+	for (const [index, unit] of units.entries()) {
+		const factor = factors[index];
+		if (bytes >= factor && bytes % (factor / 4) === 0) return `${bytes / factor} ${unit}`;
+	}
+	return `${bytes} bytes`;
+}
+/** Status keys: codes first in numeric order, then ranges, then `default`. */
+function compareStatuses(a, b) {
+	const rank = (status) => {
+		if (status === "default") return 2;
+		return /X/.test(status) ? 1 : 0;
+	};
+	return rank(a) - rank(b) || compareStrings(a, b);
+}
+/** A handler name as written in a class body: `get`, or `'get-item'` for a quoted key. */
+function handlerKey(name) {
+	return /^[A-Za-z_$][\w$]*$/.test(name) ? name : `'${name.replace(/['\\]/g, "\\$&")}'`;
+}
+/** The body type named by the hints (`ItemController` → `ItemResponse`): an example, never a literal `Body`. */
+function exampleBodyType(controller) {
+	const base = controller.replace(/Controller$/, "");
+	return base === "" ? "ResponseBody" : `${base}Response`;
+}
+// src/compiler/schemas.ts
+/** Standard Schemas referenced by the document, by identity. */
+var Slots = class {
+	#slots = /* @__PURE__ */ new Map();
+	#names = /* @__PURE__ */ new Map();
+	#report;
+	#reserved;
+	#locate;
+	constructor(report, reserved, locate = () => void 0) {
+		this.#report = report;
+		this.#reserved = reserved;
+		this.#locate = locate;
+	}
+	/** The placeholder of `ref` with this io (registers the slot), `undefined` after a name conflict. */
+	use(ref, io) {
+		const identity = ref.identity ?? `${ref.location.file}#${ref.text}`;
+		let slot = this.#slots.get(identity);
+		if (slot === void 0) {
+			const name = componentName(ref.name.slice(ref.name.lastIndexOf(".") + 1));
+			const other = this.#names.get(name);
+			if (other !== void 0 && other.identity !== identity) {
+				this.#report({
+					code: Codes.SchemaNameConflict,
+					severity: "error",
+					message: `Two schemas are named "${name}" in the OpenAPI document: ${ref.text} and ${other.identity}`,
+					location: ref.location,
+					related: [{
+						message: "the other schema",
+						location: other.location
+					}],
+					hints: ["Rename one of the exported schemas: component names come from their export names"]
+				});
+				return;
+			}
+			if (this.#reserved().has(name)) {
+				this.#report({
+					code: Codes.SchemaNameConflict,
+					severity: "error",
+					message: `The schema ${ref.text} is named "${name}", a name reserved for the standard error components`,
+					location: ref.location,
+					hints: ["Rename the schema, or turn the standard errors off: @OpenApiDocument({ errors: false })"]
+				});
+				return;
+			}
+			this.#names.set(name, {
+				identity,
+				location: ref.location
+			});
+			slot = {
+				name,
+				ref,
+				io: /* @__PURE__ */ new Set(),
+				location: this.#locate(ref) ?? ref.location
+			};
+			this.#slots.set(identity, slot);
+		}
+		slot.io.add(io);
+		return {
+			$znight: "schema",
+			name: slot.name,
+			io
+		};
+	}
+	/** Whether a slot uses this component name. */
+	has(name) {
+		return this.#names.get(name);
+	}
+	/** Adds an io to the slot of `identity` (no effect for an unknown slot). */
+	need(identity, io) {
+		this.#slots.get(identity)?.io.add(io);
+	}
+	/** Slots sorted by name. */
+	list() {
+		return [...this.#slots.values()].sort((a, b) => compareStrings(a.name, b.name));
+	}
+};
+/** Converts shapes to JSON Schema and collects the components. */
+var Schemas = class {
+	#ctx;
+	#options;
+	#slots;
+	#strict;
+	#reserved;
+	/** Component name by named key. */
+	#names = /* @__PURE__ */ new Map();
+	/** The first named key given each component name. */
+	#keys = /* @__PURE__ */ new Map();
+	/** Components by name. */
+	#components = /* @__PURE__ */ new Map();
+	/** Every named shape seen, by key. */
+	#named = /* @__PURE__ */ new Map();
+	/** Issues reported so far, with the severity they were reported at. */
+	#reported = /* @__PURE__ */ new WeakMap();
+	#conflicts = /* @__PURE__ */ new Set();
+	constructor(ctx, options, slots) {
+		this.#ctx = ctx;
+		this.#slots = slots;
+		this.#strict = options.strict;
+		this.#reserved = options.reserved;
+		this.#options = {
+			schemaAliases: SCHEMA_ALIASES,
+			schemaMembers: SCHEMA_MEMBERS,
+			keep: KEEP,
+			jsdoc: options.jsdoc
+		};
+	}
+	/** The shape of a target with the options of the extension. */
+	shape(target) {
+		return this.#ctx.types.shape(target, this.#options);
+	}
+	/** Components computed so far, sorted by name. */
+	components() {
+		const result = {};
+		for (const name of [...this.#components.keys()].sort(compareStrings)) {
+			const schema = this.#components.get(name)?.schema;
+			if (schema !== void 0) result[name] = schema;
+		}
+		return result;
+	}
+	/** A named shape seen by a result (`undefined` for an unknown key). */
+	named(key) {
+		return this.#named.get(key);
+	}
+	/**
+	* Registers the named shapes of `result` and reports its issues. Call it before converting shapes
+	* of the result.
+	*/
+	register(result, use) {
+		for (const named of result.named.values()) this.#named.set(named.key, named);
+		for (const named of result.named.values()) this.#component(named);
+		for (const issue of result.issues) this.#issue(issue, use);
+	}
+	/** JSON Schema of the root of `result` (registers it first). */
+	fromResult(result, use) {
+		this.register(result, use);
+		return this.convert(result.root, use, "");
+	}
+	/** JSON Schema of a shape whose result was {@link register}ed. */
+	convert(shape, use, path) {
+		switch (shape.kind) {
+			case "string": return { type: "string" };
+			case "number": return { type: "number" };
+			case "boolean": return { type: "boolean" };
+			case "null": return { type: "null" };
+			case "undefined":
+			case "unknown": return {};
+			case "never": return { not: {} };
+			case "date": return {
+				type: "string",
+				format: "date-time"
+			};
+			case "url": return {
+				type: "string",
+				format: "uri"
+			};
+			case "bigint": return {
+				type: "string",
+				pattern: "^-?[0-9]+$"
+			};
+			case "binary":
+				if (path !== "") this.#warn(`${path} is binary data: inside a JSON body JSON.stringify writes it as an object of numeric keys (${use.operation})`, use, ["Send bytes as the whole body (application/octet-stream), or encode them (base64 string)"]);
+				return {
+					type: "string",
+					contentMediaType: "application/octet-stream"
+				};
+			case "literal": return {
+				type: typeof shape.value,
+				const: shape.value
+			};
+			case "array": return {
+				type: "array",
+				items: this.convert(shape.items, use, `${path}[]`)
+			};
+			case "tuple": return this.#tuple(shape, use, path);
+			case "object": return this.#object(shape.properties, shape.additional, use, path);
+			case "union": return this.#union(shape.members, use, path);
+			case "intersection": return this.#intersection(shape.members, use, path);
+			case "named": {
+				const name = this.#nameOfKey(shape.key);
+				return name === void 0 ? {} : { $ref: schemaRef(name) };
+			}
+			case "schema": return this.#slots.use(shape.ref, shape.io) ?? {};
+			case "reference":
+				this.#warn(`${path === "" ? "The type" : path} (${shape.name}) cannot be documented inside a JSON body (${use.operation})`, use, []);
+				return {};
+			case "opaque": return {};
+		}
+	}
+	/**
+	* Checks the components against the schema slots once every operation is built, whatever the order
+	* they were met in: a declaration merged with the schema it is inferred from (`const User =
+	* z.object(...)` and `interface User extends z.infer<typeof User> {}`) is documented by the schema
+	* (its output variant); another declaration with the name of a schema is ZNIGHT034.
+	*/
+	settle() {
+		for (const [name, component] of [...this.#components]) {
+			const slot = this.#slots.has(name);
+			if (slot === void 0) continue;
+			if (slot.identity === component.identity) {
+				this.#components.delete(name);
+				this.#slots.need(slot.identity, "output");
+				continue;
+			}
+			const named = this.#named.get(component.key);
+			const key = `${name}\u0000${component.key}`;
+			if (this.#conflicts.has(key)) continue;
+			this.#conflicts.add(key);
+			this.#ctx.report({
+				code: Codes.SchemaNameConflict,
+				severity: "error",
+				message: `Two schemas are named "${name}" in the OpenAPI document: the ${named?.declaration ?? "declaration"} ${named?.name ?? component.identity} and the schema ${slot.identity}`,
+				location: component.location,
+				related: [{
+					message: "the schema",
+					location: slot.location
+				}],
+				hints: ["Rename one of them: component names come from declaration and export names"]
+			});
+		}
+	}
+	#component(named) {
+		const name = this.#nameOf(named);
+		const existing = this.#components.get(name);
+		if (existing !== void 0) {
+			if (existing.key !== named.key) this.#conflict(name, named, existing);
+			return;
+		}
+		if (this.#reserved.has(name)) {
+			const key = `${name}\u0000${named.key}`;
+			if (!this.#conflicts.has(key)) {
+				this.#conflicts.add(key);
+				this.#ctx.report({
+					code: Codes.SchemaNameConflict,
+					severity: "error",
+					message: `${named.name} is named "${name}", a name reserved for the standard error components of the OpenAPI document`,
+					location: named.location,
+					hints: ["Rename one of them: component names come from declaration and export names"]
+				});
+			}
+			return;
+		}
+		const component = {
+			key: named.key,
+			identity: named.identity,
+			location: named.location,
+			schema: void 0
+		};
+		this.#components.set(name, component);
+		const use = {
+			io: "output",
+			operation: named.name,
+			part: named.name,
+			location: named.location
+		};
+		component.schema = withDoc(this.convert(named.shape, use, named.name), named.doc, (issue) => this.#tagIssue(issue));
+	}
+	#conflict(name, named, existing) {
+		const key = [named.key, existing.key].sort(compareStrings).join("\0");
+		if (this.#conflicts.has(key)) return;
+		this.#conflicts.add(key);
+		this.#ctx.report({
+			code: Codes.SchemaNameConflict,
+			severity: "error",
+			message: `Two declarations are named "${name}" in the OpenAPI document: ${named.identity} and ${existing.identity}`,
+			location: named.location,
+			related: [{
+				message: "the other declaration",
+				location: existing.location
+			}],
+			hints: ["Rename one of them: component names come from declaration names"]
+		});
+	}
+	#nameOfKey(key) {
+		const named = this.#named.get(key);
+		return named === void 0 ? void 0 : this.#nameOf(named);
+	}
+	/**
+	* The component name of a declaration: its name, then the names of its type arguments
+	* (`Page_Book`). An instantiation with an anonymous argument (`Page<{ id: string }>`), or whose
+	* name another instantiation of the same declaration already has (`Box<Book[]>`, `Box<BookArray>`),
+	* also gets a short hash of its key (`Page_object_1a2b3c4d`): two instantiations never clash.
+	*/
+	#nameOf(named) {
+		let name = this.#names.get(named.key);
+		if (name === void 0) {
+			if (named.typeArgs.length === 0) name = componentName(named.name);
+			else {
+				const args = named.typeArgs.map((arg) => this.#argName(arg));
+				name = componentName([named.name, ...args.map((arg) => arg.text)].join("_"));
+				const taken = this.#keys.get(name);
+				if (taken !== void 0 && taken !== named.key && this.#named.get(taken)?.identity === named.identity || args.some((arg) => !arg.exact)) name = `${name}_${shortHash(named.key)}`;
+			}
+			this.#names.set(named.key, name);
+			if (!this.#keys.has(name)) this.#keys.set(name, named.key);
+		}
+		return name;
+	}
+	/** The name of a type argument; `exact: false` when it does not tell the argument apart (`object`). */
+	#argName(shape) {
+		switch (shape.kind) {
+			case "named": return {
+				text: this.#nameOfKey(shape.key) ?? "unknown",
+				exact: true
+			};
+			case "literal": return {
+				text: String(shape.value),
+				exact: true
+			};
+			case "array": {
+				const items = this.#argName(shape.items);
+				return {
+					text: `${items.text}Array`,
+					exact: items.exact
+				};
+			}
+			case "union":
+			case "intersection": {
+				const members = shape.members.map((member) => this.#argName(member));
+				return {
+					text: members.map((member) => member.text).join(shape.kind === "union" ? "_or_" : "_and_"),
+					exact: members.every((member) => member.exact)
+				};
+			}
+			case "schema": return {
+				text: componentName(shape.ref.name),
+				exact: true
+			};
+			case "reference": return {
+				text: shape.name,
+				exact: shape.typeArgs.length === 0
+			};
+			case "opaque":
+			case "object":
+			case "tuple": return {
+				text: shape.kind,
+				exact: false
+			};
+			default: return {
+				text: shape.kind,
+				exact: true
+			};
+		}
+	}
+	#tuple(shape, use, path) {
+		const schema = {
+			type: "array",
+			prefixItems: shape.items.map((item, index) => this.convert(item, use, `${path}[${index}]`)),
+			minItems: shape.minItems
+		};
+		if (shape.rest === void 0) {
+			schema["maxItems"] = shape.items.length;
+			schema["items"] = false;
+		} else schema["items"] = this.convert(shape.rest, use, `${path}[]`);
+		return schema;
+	}
+	#object(properties, additional, use, path) {
+		const schema = { type: "object" };
+		if (properties.length > 0) {
+			const props = {};
+			for (const property of properties) {
+				const converted = this.convert(property.shape, use, path === "" ? property.name : `${path}.${property.name}`);
+				props[property.name] = withDoc(converted, property.doc, (issue) => this.#tagIssue(issue));
+			}
+			schema["properties"] = props;
+			const required = properties.filter((property) => !property.optional).map((property) => property.name).sort(compareStrings);
+			if (required.length > 0) schema["required"] = required;
+		}
+		if (additional !== void 0) schema["additionalProperties"] = this.convert(additional, use, `${path}[string]`);
+		return schema;
+	}
+	#union(members, use, path) {
+		const defined = members.filter((member) => member.kind !== "undefined");
+		const nullable = defined.some((member) => member.kind === "null");
+		const rest = defined.filter((member) => member.kind !== "null");
+		if (rest.length === 0) return nullable ? { type: "null" } : {};
+		if (rest.every((member) => member.kind === "literal")) {
+			const values = rest.map((member) => member.value);
+			const types = [...new Set(values.map((value) => typeof value))];
+			const schema = {};
+			if (types.length === 1) schema["type"] = nullable ? [types[0], "null"] : types[0];
+			schema["enum"] = nullable ? [...values, null] : values;
+			return schema;
+		}
+		const converted = rest.map((member) => this.convert(member, use, path));
+		if (converted.length === 1) {
+			const single = converted[0];
+			if (!nullable) return single;
+			if (typeof single["type"] === "string" && !Object.keys(single).some((key) => NOT_NULLABLE_KEYS.has(key))) return {
+				...single,
+				type: [single["type"], "null"]
+			};
+			return { anyOf: [single, { type: "null" }] };
+		}
+		const simple = converted;
+		if (simple.every((schema) => Object.keys(schema).length === 1 && typeof schema["type"] === "string")) {
+			const types = simple.map((schema) => schema["type"]);
+			return { type: nullable ? [...types, "null"] : types };
+		}
+		const discriminator = this.#discriminator(rest);
+		const list = converted.map((schema) => schema);
+		if (nullable) list.push({ type: "null" });
+		if (discriminator === void 0) return { anyOf: list };
+		const mapping = {};
+		rest.forEach((member, index) => {
+			const ref = converted[index]["$ref"];
+			if (member.kind === "named" && typeof ref === "string") mapping[String(discriminator.values[index])] = ref;
+		});
+		const schema = { oneOf: list };
+		if (Object.keys(mapping).length === rest.length) schema["discriminator"] = {
+			propertyName: discriminator.property,
+			mapping
+		};
+		return schema;
+	}
+	/** A required literal property with distinct (string) values in every object member. */
+	#discriminator(members) {
+		const objects = members.map((member) => this.#objectOf(member));
+		if (objects.some((object) => object === void 0)) return void 0;
+		const literals = objects.map((object) => {
+			const map = /* @__PURE__ */ new Map();
+			for (const property of object?.properties ?? []) if (!property.optional && property.shape.kind === "literal" && typeof property.shape.value === "string") map.set(property.name, property.shape.value);
+			return map;
+		});
+		const first = literals[0];
+		if (first === void 0) return void 0;
+		for (const property of [...first.keys()].sort(compareStrings)) {
+			if (!literals.every((map) => map.has(property))) continue;
+			const values = literals.map((map) => map.get(property));
+			if (new Set(values).size === values.length) return {
+				property,
+				values
+			};
+		}
+	}
+	/** The object structure of a shape (named declarations resolved). */
+	#objectOf(shape) {
+		if (shape.kind === "object") return shape;
+		if (shape.kind === "named") {
+			const named = this.#named.get(shape.key);
+			return named === void 0 ? void 0 : this.#objectOf(named.shape);
+		}
+		if (shape.kind === "intersection") {
+			const parts = shape.members.map((member) => this.#objectOf(member));
+			if (parts.some((part) => part === void 0)) return void 0;
+			const properties = /* @__PURE__ */ new Map();
+			for (const part of parts) for (const property of part?.properties ?? []) properties.set(property.name, property);
+			return {
+				kind: "object",
+				properties: [...properties.values()]
+			};
+		}
+	}
+	#intersection(members, use, path) {
+		const merged = this.#objectOf({
+			kind: "intersection",
+			members
+		});
+		if (merged !== void 0) {
+			const additional = members.map((member) => this.#objectOf(member)?.additional).find((value) => value !== void 0);
+			return this.#object(merged.properties, additional, use, path);
+		}
+		return { allOf: members.map((member) => this.convert(member, use, path)) };
+	}
+	#issue(issue, use) {
+		const severity = issue.reason === "bigint" && use.io === "output" || this.#strict ? "error" : "warning";
+		const reported = this.#reported.get(issue);
+		if (reported === "error" || reported === severity) return;
+		this.#reported.set(issue, severity);
+		const subject = issue.path === "" ? `The type of ${use.part}` : issue.path;
+		const location = issue.location ?? use.location;
+		const related = issue.location !== void 0 && use.location !== void 0 ? [{
+			message: `${use.part} of ${use.operation}`,
+			location: use.location
+		}] : [];
+		if (issue.reason === "bigint") {
+			const response = use.io === "output";
+			this.#ctx.report({
+				code: Codes.UnrepresentableType,
+				severity,
+				message: response ? `${subject} is a bigint: JSON.stringify throws on bigint, so ${use.operation} would answer 500` : `${subject} is a bigint: JSON has no bigint (${use.operation})`,
+				...location === void 0 ? {} : { location },
+				related,
+				hints: [response ? "Return a number or a string (String(total)), or give the type a toJSON() method" : "Declare a string and convert it (BigInt(value)), or validate the body with a schema"]
+			});
+			return;
+		}
+		this.#ctx.report({
+			code: Codes.UnrepresentableType,
+			severity,
+			message: `${subject} (${issue.text}) ${REASONS[issue.reason] ?? "has no JSON Schema"}: it is documented as any value (${use.operation})`,
+			...location === void 0 ? {} : { location },
+			related,
+			hints: HINTS[issue.reason] ?? []
+		});
+	}
+	#warn(message, use, hints) {
+		this.#ctx.report({
+			code: Codes.UnrepresentableType,
+			severity: this.#strict ? "error" : "warning",
+			message,
+			...use.location === void 0 ? {} : { location: use.location },
+			hints
+		});
+	}
+	#tagIssue(issue) {
+		this.#ctx.report({
+			code: Codes.UnrepresentableType,
+			severity: this.#strict ? "error" : "warning",
+			message: issue.message,
+			location: issue.location,
+			hints: ["JSDoc tag values are JSON (`@minimum 1`, `@example {\"id\": 1}`) or text"]
+		});
+	}
+};
+/** 8 hexadecimal characters of the SHA-256 of `text` (deterministic name suffixes). */
+function shortHash(text) {
+	return createHash("sha256").update(text).digest("hex").slice(0, 8);
+}
+/** Keywords whose meaning changes when `null` joins the type list (`enum`, `const`...): `anyOf` instead. */
+const NOT_NULLABLE_KEYS = /* @__PURE__ */ new Set([
+	"$ref",
+	"enum",
+	"const",
+	"anyOf",
+	"oneOf",
+	"allOf",
+	"not"
+]);
+const REASONS = {
+	function: "is a function, which JSON.stringify skips",
+	symbol: "is a symbol, which JSON.stringify skips",
+	"type-parameter": "is an unbound type parameter",
+	"non-json": "is not serialised as declared by JSON.stringify",
+	mapped: "is a mapped type the compiler cannot expand",
+	conditional: "is a conditional type the compiler cannot expand",
+	typeof: "is a typeof type that is not a schema",
+	"indexed-access": "is an indexed access type the compiler cannot resolve",
+	"type-operator": "uses a type operator the compiler cannot expand",
+	this: "is a this type",
+	unresolved: "cannot be resolved",
+	"missing-annotation": "has no type annotation",
+	"to-json": "has a toJSON() method without return type annotation",
+	recursive: "is a recursion the compiler cannot follow",
+	unsupported: "has no JSON Schema"
+};
+const HINTS = {
+	"non-json": ["Map, Set, RegExp and Error become {} in JSON: use an array or a record, or add a toJSON() method"],
+	"to-json": ["Annotate the return type of toJSON(): toJSON(): BookJson"],
+	"missing-annotation": ["Annotate the type: the compiler reads annotations only"],
+	conditional: ["Declare the structure with an interface, or describe the body with @ApiResponse({ schema })"],
+	mapped: ["Declare the structure with an interface, or describe the body with @ApiResponse({ schema })"],
+	"type-parameter": ["Give the type arguments explicitly"],
+	function: ["Remove the member from the transported type"]
+};
+const NUMERIC_TAGS = /* @__PURE__ */ new Set([
+	"minimum",
+	"maximum",
+	"exclusiveMinimum",
+	"exclusiveMaximum",
+	"multipleOf"
+]);
+const COUNT_TAGS = /* @__PURE__ */ new Set([
+	"minLength",
+	"maxLength",
+	"minItems",
+	"maxItems"
+]);
+/** Adds the JSDoc text and tags of `doc` to a schema (§6.2 "JSDoc tags on types and properties"). */
+function withDoc(schema, doc, report) {
+	if (doc === void 0) return schema;
+	const result = { ...schema };
+	if (doc.text !== "") result["description"] = doc.text;
+	for (const tag of doc.tags) {
+		const text = tag.text.trim();
+		const invalid = (expected) => report({
+			message: `Invalid @${tag.name} value ${JSON.stringify(text)}: expected ${expected}`,
+			location: tag.location
+		});
+		if (tag.name === "deprecated") result["deprecated"] = true;
+		else if (tag.name === "example") result["examples"] = [...Array.isArray(result["examples"]) ? result["examples"] : [], parseTagValue(stripFence(text))];
+		else if (tag.name === "default") result["default"] = parseTagValue(text);
+		else if (tag.name === "format") {
+			if (text === "" || /\s/.test(text)) invalid("a format name (date, email, int32...)");
+			else {
+				result["format"] = text;
+				if ((text === "int32" || text === "int64") && result["type"] === "number") result["type"] = "integer";
+			}
+		} else if (NUMERIC_TAGS.has(tag.name)) {
+			const value = parseTagValue(text);
+			if (typeof value === "number" && Number.isFinite(value)) result[tag.name] = value;
+			else invalid("a number");
+		} else if (COUNT_TAGS.has(tag.name)) {
+			const value = parseTagValue(text);
+			if (typeof value === "number" && Number.isInteger(value) && value >= 0) result[tag.name] = value;
+			else invalid("a non-negative integer");
+		} else if (tag.name === "pattern") try {
+			new RegExp(text, "u");
+			result["pattern"] = text;
+		} catch {
+			invalid("a regular expression");
+		}
+		else if (tag.name === "uniqueItems") {
+			const value = text === "" ? true : parseTagValue(text);
+			if (typeof value === "boolean") result["uniqueItems"] = value;
+			else invalid("true or false");
+		}
+	}
+	return result;
+}
+/** A tag value: JSON when it parses, the text otherwise. */
+function parseTagValue(text) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+function stripFence(text) {
+	return /^```[\w-]*\n([\s\S]*?)\n```$/.exec(text)?.[1]?.trim() ?? text;
+}
+// src/compiler/validate.ts
+/**
+* Models by compile. The key is `graph.extensions`: the validate and generate contexts of one
+* compile get different graph objects (diagnostics, pruning) sharing this array.
+*/
+const models = /* @__PURE__ */ new WeakMap();
+/** `validate` of the extension. */
+function validateOpenApi(ctx) {
+	models.set(ctx.graph.extensions, buildModel(ctx));
+}
+/** The model built by `validate` for the compile of `graph`. */
+function modelOf(graph) {
+	return models.get(graph.extensions);
+}
+function buildModel(ctx) {
+	const schemes = new SchemeRegistry(ctx);
+	const document = readDocument(ctx, schemes);
+	const reserved = new Set(document.errors === false ? [] : [ERROR_COMPONENTS.body, ERROR_COMPONENTS.validation]);
+	const slots = new Slots((diagnostic) => ctx.report(diagnostic), () => reserved, (ref) => declarationOf(ctx, ref.identity));
+	const schemas = new Schemas(ctx, {
+		jsdoc: document.jsdoc,
+		strict: document.strict,
+		reserved
+	}, slots);
+	const errorsSlot = document.errors === false || document.errors.schema === void 0 ? void 0 : slots.use(document.errors.schema, "output");
+	const { operations, tagDescriptions } = buildOperations({
+		ctx,
+		document,
+		schemes,
+		schemas,
+		slots
+	});
+	schemas.settle();
+	const rootSecurity = document.security === void 0 ? void 0 : schemes.objects(document.security);
+	const securitySchemes = {};
+	for (const name of [...schemes.used.keys()].sort(compareStrings)) securitySchemes[name] = schemes.used.get(name)?.definition;
+	return {
+		document: documentTemplate(document, rootSecurity),
+		operations,
+		components: schemas.components(),
+		securitySchemes,
+		slots: slots.list(),
+		errors: errorsOf(document.errors, errorsSlot?.name),
+		tagDescriptions,
+		root: ctx.options.root
+	};
+}
+function errorsOf(errors, schema) {
+	if (errors === false) return void 0;
+	return schema === void 0 ? { contentType: errors.contentType } : {
+		contentType: errors.contentType,
+		schema
+	};
+}
+/** Location of the declaration of an identity (`export const CreateBook = ...`). */
+function declarationOf(ctx, identity) {
+	if (identity === void 0) return void 0;
+	const symbol = ctx.project.lookupIdentity(identity);
+	if (symbol.kind !== "declaration") return void 0;
+	const declaration = symbol.declarations[0];
+	if (declaration === void 0) return void 0;
+	return ctx.project.getFile(declaration.file)?.location(declaration.span);
+}
+/** `{ file, line, column }` of a location, the file relative to `root`. */
+function sourceOf(location, root) {
+	return {
+		file: location.file.startsWith(`${root}/`) ? location.file.slice(root.length + 1) : location.file,
+		line: location.line,
+		column: location.column
+	};
+}
+// src/compiler/generate.ts
+/** `generate` of the extension. */
+function generateOpenApi(ctx) {
+	const model = modelOf(ctx.graph) ?? emptyModel(ctx.options.root);
+	const operations = model.operations.map((operation) => ({
+		controller: operation.controller,
+		handler: operation.handler,
+		route: operation.route,
+		method: operation.method,
+		path: operation.path,
+		operation: operation.operation
+	}));
+	const slots = model.slots.map((slot) => ({
+		name: slot.name,
+		io: [...slot.io].sort()
+	}));
+	const fingerprint = fingerprintOf({
+		version: 1,
+		document: model.document,
+		operations,
+		components: model.components,
+		securitySchemes: model.securitySchemes,
+		schemas: slots,
+		errors: model.errors,
+		tagDescriptions: model.tagDescriptions
+	});
+	const lit = (value) => ctx.lit(value);
+	const entries = [
+		["version", lit(1)],
+		["fingerprint", lit(fingerprint)],
+		["document", lit(model.document)],
+		["operations", lit(operations)],
+		["components", lit(model.components)],
+		["securitySchemes", lit(model.securitySchemes)],
+		["schemas", ctx.arr(model.slots.map((slot) => ctx.obj([
+			["name", slot.name],
+			["schema", ctx.importValue(slot.ref)],
+			["io", lit([...slot.io].sort())],
+			["source", lit(sourceOf(slot.location, model.root))]
+		])))]
+	];
+	if (model.errors !== void 0) entries.push(["errors", lit(model.errors)]);
+	if (Object.keys(model.tagDescriptions).length > 0) entries.push(["tagDescriptions", lit(model.tagDescriptions)]);
+	return ctx.obj(entries);
+}
+/** SHA-256 (base64url) of the canonical JSON of the section (schema values replaced by their names). */
+function fingerprintOf(section) {
+	return createHash("sha256").update(canonicalJson(section)).digest("base64url");
+}
+function emptyModel(root) {
+	return {
+		document: {
+			openapi: OPENAPI_VERSION,
+			info: {
+				title: "API",
+				version: "0.0.0"
+			}
+		},
+		operations: [],
+		components: {},
+		securitySchemes: {},
+		slots: [],
+		errors: { contentType: "application/json" },
+		tagDescriptions: {},
+		root
+	};
+}
+// src/compiler/index.ts
+/** Decorators owned by the extension, by canonical identity (static / value arguments, §4.6). */
+const decorators = Object.freeze({
+	[Ids.OpenApiDocument]: {
+		targets: ["class"],
+		params: ["value"]
+	},
+	[Ids.ApiOperation]: {
+		targets: ["method"],
+		params: ["static"]
+	},
+	[Ids.ApiTags]: {
+		targets: ["class", "method"],
+		params: [],
+		rest: "static"
+	},
+	[Ids.ApiResponse]: {
+		targets: ["method"],
+		params: ["static", "value"]
+	},
+	[Ids.ApiBody]: {
+		targets: ["method"],
+		params: ["value"]
+	},
+	[Ids.ApiQuery]: {
+		targets: ["method"],
+		params: ["static", "static"]
+	},
+	[Ids.ApiHeader]: {
+		targets: ["class", "method"],
+		params: ["static", "static"]
+	},
+	[Ids.ApiSecurity]: {
+		targets: ["class", "method"],
+		params: [],
+		rest: "value"
+	},
+	[Ids.ApiExclude]: {
+		targets: ["class", "method"],
+		params: []
+	}
+});
+/** The `@znight/openapi` compiler extension. */
+const openapi = Object.freeze({
+	apiVersion: 1,
+	name: EXTENSION_NAME,
+	decorators,
+	analyzeClass: analyzeOpenApiClass,
+	validate: validateOpenApi,
+	generate: generateOpenApi
+});
+export { openapi as default };
+
+//# sourceMappingURL=compiler.mjs.map