@znight/openapi 0.0.0-stage → 0.1.0

package/dist/build-DXunOzlI.mjs

@@ -0,0 +1,733 @@
+import { f as jsonEquals, l as compareStrings, m as schemaRef, n as ERROR_RESPONSES, p as reasonPhrase, t as ERROR_COMPONENTS, u as componentName } from "./shared-BZxtyaB0.mjs";
+import { ErrorCode, ZnightError, displayName } from "@znight/core";
+// src/metadata.ts
+/** Format version of {@link OpenApiMetadata}. */
+const OPENAPI_METADATA_VERSION = 1;
+// src/converters.ts
+function propsOf(schema) {
+	const props = schema["~standard"];
+	return typeof props === "object" && props !== null ? props : void 0;
+}
+/** `vendor` of a Standard Schema (`zod`, `valibot`, `arktype`...). */
+function vendorOf(schema) {
+	const vendor = propsOf(schema)?.vendor;
+	return typeof vendor === "string" ? vendor : "unknown";
+}
+/** How a date travels in JSON: an ISO 8601 string. */
+const DATE_TIME = Object.freeze({
+	type: "string",
+	format: "date-time"
+});
+/**
+* Zod dates are serialised with `Date.prototype.toJSON`: in responses they are ISO strings. A
+* coerced date (`z.coerce.date()`) reads a string in requests (query, path, body). Other
+* unrepresentable parts throw (or become `{}` when lenient).
+*/
+function zodOptions(context) {
+	return { unrepresentable: (site) => {
+		const def = site.zodSchema?._zod?.def;
+		if (def?.type === "date" && (context.io === "output" || def.coerce === true)) return { ...DATE_TIME };
+		return context.lenient ? "any" : "throw";
+	} };
+}
+/**
+* `@valibot/to-json-schema` options: dates of responses are ISO strings (`Date.prototype.toJSON`),
+* other unrepresentable parts throw (or are left out when lenient).
+*/
+function valibotOptions(context) {
+	return {
+		...context.lenient ? { errorMode: "ignore" } : {},
+		overrideSchema: (site) => context.io === "output" && site.valibotSchema?.type === "date" ? { ...DATE_TIME } : void 0
+	};
+}
+function callStandard(props, context, libraryOptions) {
+	const convert = props?.jsonSchema?.[context.io];
+	if (typeof convert !== "function") return void 0;
+	return convert.call(props?.jsonSchema, {
+		target: context.target,
+		...libraryOptions === void 0 ? {} : { libraryOptions }
+	});
+}
+/**
+* Standard JSON Schema (`schema['~standard'].jsonSchema[io]({ target: 'draft-2020-12' })`): Zod ≥ 4.2,
+* ArkType ≥ 2.1.28 and every library implementing the interface.
+*/
+const standardJsonSchemaConverter = Object.freeze({
+	name: "standard-json-schema",
+	convert(schema, context) {
+		const props = propsOf(schema);
+		if (typeof props?.jsonSchema?.[context.io] !== "function") return void 0;
+		return callStandard(props, context, props.vendor === "zod" ? zodOptions(context) : void 0);
+	}
+});
+/** Valibot schemas (no `~standard.jsonSchema`) through `toStandardJsonSchema()` of `@valibot/to-json-schema`. */
+const valibotConverter = Object.freeze({
+	name: "valibot",
+	async convert(schema, context) {
+		const props = propsOf(schema);
+		if (props?.vendor !== "valibot" || props.jsonSchema !== void 0) return void 0;
+		let module;
+		try {
+			module = await import("@valibot/to-json-schema");
+		} catch (error) {
+			throw new Error("Valibot schemas need the optional peer @valibot/to-json-schema (npm install @valibot/to-json-schema)", { cause: error });
+		}
+		if (typeof module.toStandardJsonSchema !== "function") throw new Error("@valibot/to-json-schema has no toStandardJsonSchema(): install version 1.5 or later");
+		return callStandard(propsOf(module.toStandardJsonSchema(schema)), context, valibotOptions(context));
+	}
+});
+/** Built-in converters, tried after the user's. */
+const BUILT_IN_CONVERTERS = Object.freeze([standardJsonSchemaConverter, valibotConverter]);
+// src/build.ts
+/** Reads and checks `metadata.extensions.openapi` (ZNIGHT030 when missing, ZNIGHT018 for another version). */
+function openApiSection(metadata) {
+	const section = (metadata?.extensions)?.openapi;
+	if (section === void 0 || section === null || typeof section !== "object") throw new ZnightError(ErrorCode.InvalidOpenApiDefinition, "The metadata has no OpenAPI section (metadata.extensions.openapi)", { hints: ["Import @znight/openapi in a scanned file (src/main.ts imports OpenApiPlugin) and regenerate the container (znight generate)"] });
+	const version = section.version;
+	if (version !== 1) throw new ZnightError(ErrorCode.VersionMismatch, `Unsupported metadata.extensions.openapi version ${JSON.stringify(version)} (this @znight/openapi reads version 1)`, { hints: ["Use the same version of @znight/compiler and @znight/openapi, then regenerate the container"] });
+	const value = section;
+	if (!Array.isArray(value.operations) || !Array.isArray(value.schemas) || typeof value.document !== "object") throw new ZnightError(ErrorCode.InvalidOpenApiDefinition, "Malformed metadata.extensions.openapi", { hints: ["Regenerate the container (znight generate)"] });
+	return value;
+}
+/**
+* Assembles the OpenAPI 3.1 document of an application from its generated metadata: converts the
+* Standard Schemas (user converters, Standard JSON Schema, Valibot), hoists their `$defs`, names
+* the components, fills the placeholders of the compiler, applies `filter`, prunes the unused
+* components, applies `transform`, deep-freezes and serialises once.
+*
+* @throws ZnightError ZNIGHT030 (no OpenAPI section), ZNIGHT018 (another format version), ZNIGHT034
+*   (component name conflict), ZNIGHT037 (schema conversion, unless `unrepresentable: 'warn'`).
+*/
+async function buildOpenApiDocument(metadata, options = {}) {
+	const started = performance.now();
+	const section = openApiSection(metadata);
+	const warnings = [];
+	const lenient = options.unrepresentable === "warn";
+	const converters = [...options.converters ?? [], ...BUILT_IN_CONVERTERS];
+	const failures = [];
+	const converted = /* @__PURE__ */ new Map();
+	for (const slot of section.schemas) {
+		const entry = {};
+		for (const io of [...slot.io].sort()) {
+			const result = await convertSlot(slot, io, converters, false);
+			if (result.schema !== void 0) {
+				entry[io] = result.schema;
+				continue;
+			}
+			if (!lenient) {
+				failures.push(result.message);
+				continue;
+			}
+			const retried = await convertSlot(slot, io, converters, true);
+			entry[io] = retried.schema ?? {};
+			warnings.push({
+				code: ErrorCode.SchemaConversionFailed,
+				message: `${result.message}; documented as ${retried.schema === void 0 ? "any value ({})" : "an approximation"}`,
+				hints: []
+			});
+		}
+		converted.set(slot.name, entry);
+	}
+	if (failures.length > 0) throw new ZnightError(ErrorCode.SchemaConversionFailed, `Cannot convert ${failures.length === 1 ? "a schema" : `${failures.length} schemas`} to JSON Schema:\n${failures.map((line) => `  - ${line}`).join("\n")}`, { hints: ["Add a converter (OpenApiPlugin.configure({ converters }), --converters), or document the schema with unrepresentable: \"warn\""] });
+	const schemas = /* @__PURE__ */ new Map();
+	const owners = /* @__PURE__ */ new Map();
+	const define = (name, schema, owner) => {
+		const existing = schemas.get(name);
+		if (existing === void 0) {
+			schemas.set(name, schema);
+			owners.set(name, owner);
+			return;
+		}
+		if (jsonEquals(existing, schema)) return;
+		throw new ZnightError(ErrorCode.SchemaNameConflict, `Two different schemas are named "${name}" in the OpenAPI document (${owners.get(name)} and ${owner})`, { hints: ["Rename one of them (exported schema names and ids of hoisted definitions name the components)"] });
+	};
+	for (const [name, schema] of Object.entries(section.components ?? {})) define(name, schema, "a TypeScript declaration");
+	const named = nameConverted(section.schemas, converted);
+	for (const item of named.components) define(item.name, item.schema, item.owner);
+	const slotNames = named.slots;
+	const errors = section.errors;
+	const responses = {};
+	if (errors !== void 0) {
+		let body;
+		let validation;
+		if (errors.schema === void 0) {
+			define(ERROR_COMPONENTS.body, HTTP_ERROR_BODY, "the standard errors");
+			define(ERROR_COMPONENTS.validation, VALIDATION_ERROR_BODY, "the standard errors");
+			body = ERROR_COMPONENTS.body;
+			validation = ERROR_COMPONENTS.validation;
+		} else {
+			body = slotNames.get(errors.schema)?.output ?? errors.schema;
+			validation = body;
+		}
+		const response = (status, name) => ({
+			description: reasonPhrase(status),
+			content: { [errors.contentType]: { schema: { $ref: schemaRef(name) } } }
+		});
+		responses[ERROR_RESPONSES.badRequest] = response("400", validation);
+		responses[ERROR_RESPONSES.payloadTooLarge] = response("413", body);
+		responses[ERROR_RESPONSES.unsupportedMediaType] = response("415", body);
+	}
+	const duplicates = [];
+	const resolve = (value, where = "") => replacePlaceholders(value, slotNames, schemas, (parameter, slot) => duplicates.push(`${where}: the ${parameter.in} parameter "${parameter.name}" of the schema ${slot}`));
+	for (const [name, schema] of schemas) schemas.set(name, resolve(schema));
+	const views = operationViews(metadata, section);
+	const paths = {};
+	let operations = 0;
+	section.operations.forEach((definition, index) => {
+		const view = views[index];
+		if (options.filter !== void 0 && !options.filter(view)) return;
+		let item = paths[definition.path];
+		if (item === void 0) {
+			item = {};
+			paths[definition.path] = item;
+		}
+		item[definition.method] = resolve(definition.operation, `${definition.method.toUpperCase()} ${definition.path}`);
+		operations++;
+	});
+	if (duplicates.length > 0) warnings.push({
+		code: ErrorCode.InconsistentOperation,
+		message: `${duplicates.length === 1 ? "A parameter expanded from a whole-object schema is" : "Parameters expanded from whole-object schemas are"} already documented (OpenAPI forbids two parameters with one name and location), the duplicate is dropped:\n${duplicates.map((line) => `  - ${line}`).join("\n")}`,
+		hints: ["Remove the property from the schema, or the @Query('name') / @ApiQuery('name') that reads it again"]
+	});
+	const template = section.document;
+	const document = { openapi: template.openapi };
+	document["info"] = options.info === void 0 ? template.info : {
+		...template.info,
+		...options.info
+	};
+	const servers = options.servers ?? template.servers ?? (options.prefix !== void 0 && options.prefix !== "" && options.prefix !== "/" ? [{ url: options.prefix }] : void 0);
+	if (servers !== void 0) document["servers"] = servers;
+	if (template.security !== void 0) document["security"] = template.security;
+	const tags = tagsOf(template.tags ?? [], paths, section.tagDescriptions ?? {});
+	if (tags.length > 0) document["tags"] = tags;
+	if (template.externalDocs !== void 0) document["externalDocs"] = template.externalDocs;
+	document["paths"] = paths;
+	const components = prune(document, {
+		schemas: Object.fromEntries([...schemas].sort(([a], [b]) => compareStrings(a, b))),
+		responses,
+		securitySchemes: section.securitySchemes ?? {}
+	});
+	if (Object.keys(components).length > 0) document["components"] = components;
+	for (const [key, value] of Object.entries(template)) if (key.startsWith("x-") && value !== void 0) document[key] = value;
+	document["x-znight-fingerprint"] = section.fingerprint;
+	const transformed = options.transform === void 0 ? document : options.transform(document);
+	const json = `${JSON.stringify(transformed, null, 2)}\n`;
+	const frozen = deepFreeze(JSON.parse(json));
+	const componentCount = Object.keys(frozen.components?.schemas ?? {}).length;
+	return {
+		document: frozen,
+		json,
+		warnings,
+		stats: {
+			operations,
+			schemas: componentCount,
+			durationMs: performance.now() - started
+		}
+	};
+}
+/** Root keys of a document, in the order {@link buildOpenApiDocument} writes them. */
+const ROOT_ORDER = [
+	"openapi",
+	"info",
+	"servers",
+	"security",
+	"tags",
+	"externalDocs",
+	"paths",
+	"components"
+];
+/**
+* Applies the runtime options of {@link buildOpenApiDocument} to a prebuilt document (`OpenApiPlugin`
+* with `document: { file }`), so that a file and a build serve the same document: `filter` (the
+* operations are matched by path and method, unreferenced components and unused tags are pruned),
+* `info`, `servers`, else the `prefix` rule when the file declares no servers, then `transform`.
+* `undefined` when there is nothing to apply (the file is served as is).
+*/
+function applyDocumentOptions(text, metadata, options) {
+	const document = JSON.parse(text);
+	const prefixed = document["servers"] === void 0 && options.prefix !== void 0 && options.prefix !== "" && options.prefix !== "/";
+	if (options.filter === void 0 && options.info === void 0 && options.servers === void 0 && options.transform === void 0 && !prefixed) return;
+	if (options.filter !== void 0) filterDocument(document, metadata, options.filter);
+	if (options.info !== void 0) document["info"] = {
+		...document["info"],
+		...options.info
+	};
+	if (options.servers !== void 0) document["servers"] = options.servers;
+	else if (prefixed) document["servers"] = [{ url: options.prefix }];
+	const ordered = {};
+	for (const key of ROOT_ORDER) if (document[key] !== void 0) ordered[key] = document[key];
+	for (const [key, value] of Object.entries(document)) if (!(key in ordered)) ordered[key] = value;
+	const transformed = options.transform === void 0 ? ordered : options.transform(ordered);
+	const json = `${JSON.stringify(transformed, null, 2)}\n`;
+	return {
+		document: deepFreeze(JSON.parse(json)),
+		json
+	};
+}
+/** Removes the operations `filter` rejects, the paths left empty, the unused tags and components. */
+function filterDocument(document, metadata, filter) {
+	const section = openApiSection(metadata);
+	const views = /* @__PURE__ */ new Map();
+	for (const view of operationViews(metadata, section)) views.set(`${view.method} ${view.path}`, view);
+	const paths = {};
+	for (const [path, item] of Object.entries(document["paths"] ?? {})) {
+		const kept = {};
+		let methods = 0;
+		for (const [key, value] of Object.entries(item)) {
+			if (METHODS.has(key)) {
+				const view = views.get(`${key} ${path}`);
+				if (view !== void 0 && !filter(view)) continue;
+				methods++;
+			}
+			kept[key] = value;
+		}
+		if (methods > 0) paths[path] = kept;
+	}
+	document["paths"] = paths;
+	if (Array.isArray(document["tags"])) {
+		const declared = new Set((section.document.tags ?? []).map((tag) => tag.name));
+		const used = new Set(tagsOf([], paths, {}).map((tag) => tag.name));
+		const tags = document["tags"].filter((tag) => declared.has(tag.name) || used.has(tag.name));
+		if (tags.length > 0) document["tags"] = tags;
+		else delete document["tags"];
+	}
+	const components = document["components"] ?? {};
+	delete document["components"];
+	const pruned = prune(document, {
+		schemas: components["schemas"] ?? {},
+		responses: components["responses"] ?? {},
+		securitySchemes: components["securitySchemes"] ?? {}
+	});
+	const result = {};
+	for (const [kind, value] of Object.entries(components)) if (kind !== "schemas" && kind !== "responses" && kind !== "securitySchemes") result[kind] = value;
+	else if (pruned[kind] !== void 0) result[kind] = pruned[kind];
+	if (Object.keys(result).length > 0) document["components"] = result;
+}
+const METHODS = /* @__PURE__ */ new Set([
+	"get",
+	"put",
+	"post",
+	"delete",
+	"options",
+	"head",
+	"patch",
+	"trace"
+]);
+async function convertSlot(slot, io, converters, lenient) {
+	const where = slot.source === void 0 ? "" : ` (${slot.source.file}:${slot.source.line}:${slot.source.column})`;
+	const label = `${slot.name}${where}, ${vendorOf(slot.schema)} schema, ${io}`;
+	for (const converter of converters) {
+		let result;
+		try {
+			result = await converter.convert(slot.schema, {
+				io,
+				target: "draft-2020-12",
+				lenient
+			});
+		} catch (error) {
+			return {
+				schema: void 0,
+				message: `${label}: the converter "${converter.name}" failed: ${error instanceof Error ? error.message : String(error)}`
+			};
+		}
+		if (result === void 0) continue;
+		if (typeof result !== "object" || result === null || Array.isArray(result)) return {
+			schema: void 0,
+			message: `${label}: the converter "${converter.name}" returned ${Array.isArray(result) ? "an array" : typeof result} instead of a JSON Schema object`
+		};
+		return {
+			schema: result,
+			message: ""
+		};
+	}
+	return {
+		schema: void 0,
+		message: `${label}: no converter supports it (the library implements no Standard JSON Schema)`
+	};
+}
+/** Drops `$schema` and `$id` (top level). */
+function clean(schema) {
+	const { $schema: _schema, $id: _id, ...rest } = schema;
+	return JSON.parse(JSON.stringify(rest));
+}
+/**
+* Definition names a library generates for anonymous sub-schemas (Zod: `__schema0` for a recursive
+* schema without id). They are local to one conversion, so they are scoped to their slot.
+*/
+const ANONYMOUS_DEFINITION = /^__schema(\d+)$/;
+/** Marks the references between definitions until the final names are known (`\0<name>\0<rest>`). */
+const MARK = "\0";
+/**
+* Names the converted schemas (steps 3 and 4 of §7.3): hoists `$defs` / `definitions` into
+* components, scopes anonymous definitions to their slot (`Tree_schema0`), takes the definition as
+* the slot component when the root only references it (`.meta({ id })` equal to the export name),
+* and gives `<Name>Input` to the input variant of every schema — slot or definition — whose input
+* and output JSON Schemas differ (directly or through the definitions it references). Two different
+* schemas of one io under one name are ZNIGHT034.
+*/
+function nameConverted(slots, converted) {
+	const units = [];
+	for (const slot of slots) {
+		const entry = converted.get(slot.name) ?? {};
+		for (const io of ["output", "input"]) {
+			const schema = entry[io];
+			if (schema !== void 0) units.push(splitUnit(slot.name, io, clean(schema)));
+		}
+	}
+	const variants = /* @__PURE__ */ new Map();
+	for (const unit of units) for (const { name, body, owner } of unit.bodies) {
+		let entry = variants.get(name);
+		if (entry === void 0) {
+			entry = { owners: {} };
+			variants.set(name, entry);
+		}
+		const existing = entry[unit.io];
+		if (existing === void 0) {
+			entry[unit.io] = body;
+			entry.owners[unit.io] = owner;
+		} else if (!jsonEquals(existing, body)) throw new ZnightError(ErrorCode.SchemaNameConflict, `Two different schemas are named "${name}" in the OpenAPI document (${entry.owners[unit.io]} and ${owner})`, { hints: ["Rename one of them (exported schema names and ids of hoisted definitions name the components)"] });
+	}
+	const split = /* @__PURE__ */ new Set();
+	for (const [name, entry] of variants) if (entry.input !== void 0 && entry.output !== void 0 && !jsonEquals(entry.input, entry.output)) split.add(name);
+	for (let changed = true; changed;) {
+		changed = false;
+		for (const [name, entry] of variants) {
+			if (split.has(name) || entry.input === void 0 || entry.output === void 0) continue;
+			if ([...referencedNames(entry.input)].some((target) => split.has(target))) {
+				split.add(name);
+				changed = true;
+			}
+		}
+	}
+	const nameFor = (name, io) => io === "input" && split.has(name) ? `${name}Input` : name;
+	const components = [];
+	for (const [name, entry] of variants) {
+		if (entry.output !== void 0) components.push({
+			name,
+			schema: resolveMarks(entry.output, "output", nameFor),
+			owner: entry.owners["output"]
+		});
+		if (entry.input !== void 0 && (entry.output === void 0 || split.has(name))) components.push({
+			name: nameFor(name, "input"),
+			schema: resolveMarks(entry.input, "input", nameFor),
+			owner: entry.owners["input"]
+		});
+	}
+	const names = /* @__PURE__ */ new Map();
+	for (const slot of slots) {
+		const entry = converted.get(slot.name) ?? {};
+		const result = {};
+		if (entry.output !== void 0) result.output = nameFor(slot.name, "output");
+		if (entry.input !== void 0) result.input = nameFor(slot.name, "input");
+		names.set(slot.name, result);
+	}
+	return {
+		components,
+		slots: names
+	};
+}
+/**
+* Splits a converted schema into its root and its `$defs` / `definitions` (at every level), with
+* global names: the slot name for the root, `<slot>_schemaN` for anonymous definitions, the
+* definition name (a library id) otherwise. Inside an OpenAPI document `#` is the document, not the
+* schema, so every local reference is rewritten (`#/$defs/X`, `#`, `#/properties/...`).
+*/
+function splitUnit(slot, io, schema) {
+	const defs = /* @__PURE__ */ new Map();
+	const collect = (value) => {
+		if (typeof value !== "object" || value === null) return;
+		if (Array.isArray(value)) {
+			for (const item of value) collect(item);
+			return;
+		}
+		for (const key of ["$defs", "definitions"]) {
+			const block = value[key];
+			if (typeof block === "object" && block !== null && !Array.isArray(block)) for (const [defName, def] of Object.entries(block)) defs.set(defName, def);
+		}
+		for (const [key, item] of Object.entries(value)) if (key !== "$defs" && key !== "definitions") collect(item);
+	};
+	collect(schema);
+	const globals = /* @__PURE__ */ new Map();
+	for (const local of defs.keys()) {
+		const anonymous = ANONYMOUS_DEFINITION.exec(local);
+		globals.set(local, anonymous === null ? componentName(local) : componentName(`${slot}_schema${anonymous[1]}`));
+	}
+	let root = schema;
+	const target = Object.keys(schema).filter((key) => key !== "$defs" && key !== "definitions").length === 1 && typeof schema["$ref"] === "string" ? localTarget(schema["$ref"]) : void 0;
+	if (target !== void 0 && target.rest === "" && defs.has(target.local)) {
+		if (globals.get(target.local) === slot || ANONYMOUS_DEFINITION.test(target.local)) {
+			root = defs.get(target.local);
+			defs.delete(target.local);
+			globals.set(target.local, slot);
+		}
+	}
+	const rewrite = (value) => {
+		if (Array.isArray(value)) return value.map(rewrite);
+		if (typeof value !== "object" || value === null) return value;
+		const result = {};
+		for (const [key, item] of Object.entries(value)) {
+			if (key === "$defs" || key === "definitions") continue;
+			if (key === "$ref" && typeof item === "string") result[key] = markRef(item, slot, globals);
+			else result[key] = rewrite(item);
+		}
+		return result;
+	};
+	const bodies = [{
+		name: slot,
+		body: rewrite(root),
+		owner: `the schema ${slot}`
+	}];
+	for (const [local, def] of defs) bodies.push({
+		name: globals.get(local),
+		body: rewrite(def),
+		owner: `a definition of ${slot}`
+	});
+	return {
+		slot,
+		io,
+		bodies
+	};
+}
+/** The local definition a reference points to (`#/$defs/X/rest`), JSON pointer and URI escapes decoded. */
+function localTarget(ref) {
+	for (const prefix of ["#/$defs/", "#/definitions/"]) {
+		if (!ref.startsWith(prefix)) continue;
+		const tail = ref.slice(prefix.length);
+		const slash = tail.indexOf("/");
+		const segment = slash === -1 ? tail : tail.slice(0, slash);
+		let local;
+		try {
+			local = decodeURIComponent(segment);
+		} catch {
+			local = segment;
+		}
+		return {
+			local: local.replaceAll("~1", "/").replaceAll("~0", "~"),
+			rest: slash === -1 ? "" : tail.slice(slash)
+		};
+	}
+}
+function markRef(ref, slot, globals) {
+	const target = localTarget(ref);
+	if (target !== void 0) return `${MARK}${globals.get(target.local) ?? componentName(target.local)}${MARK}${target.rest}`;
+	if (ref === "#") return `${MARK}${slot}${MARK}`;
+	if (ref.startsWith("#/")) return `${MARK}${slot}${MARK}${ref.slice(1)}`;
+	return ref;
+}
+function parseMark(ref) {
+	if (!ref.startsWith(MARK)) return void 0;
+	const end = ref.indexOf(MARK, 1);
+	return end === -1 ? void 0 : {
+		name: ref.slice(1, end),
+		rest: ref.slice(end + 1)
+	};
+}
+/** Global names referenced by a marked body. */
+function referencedNames(value, found = /* @__PURE__ */ new Set()) {
+	if (Array.isArray(value)) for (const item of value) referencedNames(item, found);
+	else if (typeof value === "object" && value !== null) for (const [key, item] of Object.entries(value)) {
+		const mark = key === "$ref" && typeof item === "string" ? parseMark(item) : void 0;
+		if (mark === void 0) referencedNames(item, found);
+		else found.add(mark.name);
+	}
+	return found;
+}
+/** Replaces the marked references with `#/components/schemas/<final name>`. */
+function resolveMarks(value, io, nameFor) {
+	if (Array.isArray(value)) return value.map((item) => resolveMarks(item, io, nameFor));
+	if (typeof value !== "object" || value === null) return value;
+	const result = {};
+	for (const [key, item] of Object.entries(value)) {
+		const mark = key === "$ref" && typeof item === "string" ? parseMark(item) : void 0;
+		result[key] = mark === void 0 ? resolveMarks(item, io, nameFor) : `${schemaRef(nameFor(mark.name, io))}${mark.rest}`;
+	}
+	return result;
+}
+function isPlaceholder(value) {
+	return typeof value === "object" && value !== null && typeof value.$znight === "string";
+}
+function replacePlaceholders(value, names, schemas, duplicate) {
+	if (Array.isArray(value)) {
+		if (!value.some((item) => isPlaceholder(item) && item.$znight === "parameters")) return value.map((item) => replacePlaceholders(item, names, schemas, duplicate));
+		const explicit = /* @__PURE__ */ new Set();
+		for (const item of value) {
+			const key = isPlaceholder(item) ? void 0 : parameterKey(item);
+			if (key !== void 0) explicit.add(key);
+		}
+		const expanded = /* @__PURE__ */ new Set();
+		const result = [];
+		for (const item of value) {
+			if (!isPlaceholder(item) || item.$znight !== "parameters") {
+				result.push(replacePlaceholders(item, names, schemas, duplicate));
+				continue;
+			}
+			for (const parameter of expandParameters(item, names, schemas)) {
+				const key = parameterKey(parameter);
+				if (explicit.has(key) || expanded.has(key)) {
+					duplicate(parameter, item.name);
+					continue;
+				}
+				expanded.add(key);
+				result.push(parameter);
+			}
+		}
+		return result;
+	}
+	if (typeof value !== "object" || value === null) return value;
+	if (isPlaceholder(value) && value.$znight === "schema") {
+		const name = names.get(value.name)?.[value.io] ?? value.name;
+		return { $ref: schemaRef(name) };
+	}
+	const result = {};
+	for (const [key, item] of Object.entries(value)) result[key] = replacePlaceholders(item, names, schemas, duplicate);
+	return result;
+}
+/** `in name` of a Parameter Object (header names are case-insensitive), `undefined` for a `$ref`. */
+function parameterKey(parameter) {
+	if (typeof parameter !== "object" || parameter === null) return void 0;
+	const { in: location, name } = parameter;
+	if (typeof location !== "string" || typeof name !== "string") return void 0;
+	return `${location} ${location === "header" ? name.toLowerCase() : name}`;
+}
+/** One parameter per property of the (input) object schema of a slot. */
+function expandParameters(placeholder, names, schemas) {
+	const name = names.get(placeholder.name)?.input ?? placeholder.name;
+	let schema = schemas.get(name);
+	for (let depth = 0; depth < 8 && typeof schema?.["$ref"] === "string"; depth++) schema = schemas.get(String(schema["$ref"]).slice(21));
+	const properties = schema?.["properties"];
+	if (schema === void 0 || typeof properties !== "object" || properties === null || Array.isArray(properties)) throw new ZnightError(ErrorCode.SchemaConversionFailed, `The ${placeholder.in ?? "query"} schema ${placeholder.name} is not an object schema: its properties cannot become parameters`, { hints: [`Validate the whole ${placeholder.in ?? "query"} object with an object schema (z.object({...}))`] });
+	const required = new Set(Array.isArray(schema["required"]) ? schema["required"] : []);
+	return Object.entries(properties).map(([property, propertySchema]) => {
+		const { description, ...rest } = propertySchema;
+		const parameter = {
+			name: property,
+			in: placeholder.in ?? "query"
+		};
+		if (typeof description === "string") parameter["description"] = description;
+		if (placeholder.in === "path" || required.has(property)) parameter["required"] = true;
+		parameter["schema"] = rest;
+		if ((rest["type"] === "array" || Array.isArray(rest["items"])) && placeholder.in === "query") {
+			parameter["style"] = "form";
+			parameter["explode"] = true;
+		}
+		return parameter;
+	});
+}
+/** Declared tags first (in order), then the used tags, sorted. */
+function tagsOf(declared, paths, descriptions) {
+	const tags = [...declared];
+	const known = new Set(declared.map((tag) => tag.name));
+	const used = /* @__PURE__ */ new Set();
+	for (const item of Object.values(paths)) for (const operation of Object.values(item)) for (const tag of operation.tags ?? []) used.add(tag);
+	for (const tag of [...used].sort(compareStrings)) {
+		if (known.has(tag)) continue;
+		const description = descriptions[tag];
+		tags.push(description === void 0 ? { name: tag } : {
+			name: tag,
+			description
+		});
+	}
+	return tags;
+}
+/** Components referenced by the document (paths, security), transitively. */
+function prune(document, components) {
+	const used = {
+		schemas: /* @__PURE__ */ new Set(),
+		responses: /* @__PURE__ */ new Set(),
+		securitySchemes: /* @__PURE__ */ new Set()
+	};
+	const visit = (value) => {
+		if (Array.isArray(value)) {
+			for (const item of value) visit(item);
+			return;
+		}
+		if (typeof value !== "object" || value === null) return;
+		for (const [key, item] of Object.entries(value)) if (key === "$ref" && typeof item === "string") {
+			const match = /^#\/components\/(schemas|responses)\/([^/]+)/.exec(item);
+			const kind = match?.[1];
+			const name = match?.[2] === void 0 ? void 0 : decodeURIComponent(match[2].replaceAll("~1", "/").replaceAll("~0", "~"));
+			if (kind !== void 0 && name !== void 0 && !used[kind].has(name)) {
+				used[kind].add(name);
+				visit(components[kind][name]);
+			}
+		} else if (key === "security" && Array.isArray(item)) for (const requirement of item) for (const scheme of Object.keys(requirement)) used.securitySchemes.add(scheme);
+		else visit(item);
+	};
+	visit(document);
+	const result = {};
+	for (const kind of [
+		"schemas",
+		"responses",
+		"securitySchemes"
+	]) {
+		const kept = {};
+		for (const name of Object.keys(components[kind]).sort(compareStrings)) if (used[kind].has(name)) kept[name] = components[kind][name];
+		if (Object.keys(kept).length > 0) result[kind] = kept;
+	}
+	return result;
+}
+/** Views of the operations of the section (effective route metadata from `extensions.http`). */
+function operationViews(metadata, section = openApiSection(metadata)) {
+	const http = metadata.extensions?.http;
+	const groups = /* @__PURE__ */ new Map();
+	for (const [group, definition] of Object.entries(http?.groups ?? {})) for (const key of definition.keys ?? []) groups.set(key, group);
+	const groupOf = (key) => groups.get(key) ?? key;
+	return section.operations.map((definition) => {
+		const controller = http?.controllers?.find((candidate) => candidate.token === definition.controller);
+		const routeMeta = (controller?.routes?.find((candidate) => candidate.handler === definition.handler && candidate.method === definition.route))?.meta ?? {};
+		const decided = new Set(Object.keys(routeMeta).map(groupOf));
+		const meta = {};
+		for (const [key, value] of Object.entries(controller?.meta ?? {})) if (!decided.has(groupOf(key))) meta[key] = value;
+		Object.assign(meta, routeMeta);
+		const operation = definition.operation;
+		return Object.freeze({
+			method: definition.method,
+			path: definition.path,
+			operationId: operation.operationId ?? "",
+			tags: Object.freeze([...operation.tags ?? []]),
+			controller: displayName(definition.controller),
+			handler: definition.handler,
+			meta: Object.freeze(meta)
+		});
+	});
+}
+function deepFreeze(value) {
+	if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+		Object.freeze(value);
+		for (const item of Object.values(value)) deepFreeze(item);
+	}
+	return value;
+}
+/** `HttpErrorBody` (the body of every Znight error response). */
+const HTTP_ERROR_BODY = {
+	type: "object",
+	properties: {
+		statusCode: { type: "integer" },
+		error: { type: "string" },
+		message: { type: "string" },
+		details: {}
+	},
+	required: [
+		"statusCode",
+		"error",
+		"message"
+	]
+};
+/** `ValidationErrorBody`: a 400 body; validation failures list their issues in `details`. */
+const VALIDATION_ERROR_BODY = { allOf: [{ $ref: schemaRef(ERROR_COMPONENTS.body) }, {
+	type: "object",
+	properties: { details: {
+		type: "array",
+		items: {
+			type: "object",
+			properties: {
+				path: { type: "string" },
+				message: { type: "string" }
+			},
+			required: ["path", "message"]
+		}
+	} }
+}] };
+export { BUILT_IN_CONVERTERS as a, OPENAPI_METADATA_VERSION as c, operationViews as i, buildOpenApiDocument as n, standardJsonSchemaConverter as o, openApiSection as r, valibotConverter as s, applyDocumentOptions as t };
+
+//# sourceMappingURL=build-DXunOzlI.mjs.map