@lovrozagar/honey 0.6.8 → 0.7.1

package/src/codegen-ir.ts

@@ -1,10 +1,15 @@
-import { type OpenApiSpecInput, extractOpenApiPathParams, resolveRefs } from "./codegen.ts"
+import type { OpenApiSpecInput } from "./codegen.ts"
+import { cmpCodeUnit, pascalWords } from "./codegen-lang.ts"
 
 export type IRScalarType = "string" | "number" | "integer" | "boolean" | "null"
 
 export type IRSchema =
 	| { kind: "scalar"; type: IRScalarType; format?: string; enum?: (string | number | boolean)[] }
-	| { kind: "const"; value: string | number | boolean }
+	| {
+			kind: "const"
+			value: string | number | boolean
+			/** the declared `type`, when the schema has one */ type?: IRScalarType
+	  }
 	| { kind: "object"; fields: IRField[]; additional?: IRSchema | false }
 	| { kind: "array"; items: IRSchema }
 	| { kind: "tuple"; items: IRSchema[] }
@@ -31,6 +36,12 @@ export type IRParam = {
 	name: string
 	schema: IRSchema
 	description?: string
+	/** Path params are always required. */
+	required?: boolean
+	/** A path param that may span segments (`x-honey-wildcard`). */
+	wildcard?: true
+	/** `schema.default` as declared. */
+	default?: unknown
 }
 
 export type IRMultipartPart = {
@@ -48,6 +59,8 @@ export type IRBody =
 			contentType: "multipart/form-data"
 			parts: IRMultipartPart[]
 			required: boolean
+			/** The whole form object, for emitters that type the form as one value. */
+			schema?: IRSchema
 	  }
 
 export type IRResponse = {
@@ -71,12 +84,18 @@ export type IROperation = {
 	method: string /* upper-cased HTTP method */
 	path: string /* OpenAPI path template, {param} preserved */
 	description?: string
+	summary?: string
 	params: {
 		path: IRParam[]
 		query: IRParam[]
 		header: IRParam[]
+		/** Cookie params. Most SDKs leave them to per-call options; the TypeScript SDK types them. */
+		cookie?: IRParam[]
 	}
+	/** The preferred request body: JSON first, then form, multipart, raw bytes. */
 	body?: IRBody
+	/** Every declared request body, one per content type, in the same preference order. */
+	bodies?: IRBody[]
 	responses: Record<string, IRResponse>
 	extensions: IROperationExtensions
 }
@@ -87,24 +106,33 @@ export type IRNamespace = {
 	entries: Map<string, IRTreeEntry>
 }
 
+/** How a client authenticates: the header it sends and the prefix before the token. */
+export type IRAuth = { headerName: string; prefix: string }
+
+export type IRInfo = { title?: string; description?: string; version?: string }
+
 export type IR = {
 	operations: IROperation[]
 	schemas: Record<string, IRSchema>
+	/** `description` of each component schema that has one. */
+	schemaDescriptions: Record<string, string>
 	tree: IRNamespace
+	auth: IRAuth
+	info: IRInfo
 }
 
 export function methodsOf(ns: IRNamespace): Array<[string, IROperation]> {
 	return [...ns.entries.entries()]
 		.filter((e): e is [string, Extract<IRTreeEntry, { kind: "method" }>] => e[1].kind === "method")
 		.map(([k, v]): [string, IROperation] => [k, v.op])
-		.sort(([a], [b]) => a.localeCompare(b))
+		.sort(([a], [b]) => cmpCodeUnit(a, b))
 }
 
 export function namespacesOf(ns: IRNamespace): Array<[string, IRNamespace]> {
 	return [...ns.entries.entries()]
 		.filter((e): e is [string, Extract<IRTreeEntry, { kind: "namespace" }>] => e[1].kind === "namespace")
 		.map(([k, v]): [string, IRNamespace] => [k, v.ns])
-		.sort(([a], [b]) => a.localeCompare(b))
+		.sort(([a], [b]) => cmpCodeUnit(a, b))
 }
 
 function firstDescendantId(ns: IRNamespace): string {
@@ -215,7 +243,10 @@ export function schemaToIR(schema: Record<string, unknown> | undefined): IRSchem
 	if (schema.const !== undefined) {
 		const v = schema.const
 		if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
-			return { kind: "const", value: v }
+			const out: Extract<IRSchema, { kind: "const" }> = { kind: "const", value: v }
+			const t = schema.type
+			if (t === "string" || t === "integer" || t === "number" || t === "boolean") out.type = t
+			return out
 		}
 	}
 
@@ -344,15 +375,68 @@ export function schemaToIR(schema: Record<string, unknown> | undefined): IRSchem
 
 const HTTP_METHODS = ["get", "post", "put", "patch", "delete", "head", "options"] as const
 
+export type IRPathSegment = { kind: "literal"; text: string } | { kind: "param"; name: string }
+
+/** Splits an OpenAPI path template into literal and `{param}` pieces. Any text between braces is a name. */
+export function parseOpenApiPath(path: string): IRPathSegment[] {
+	const out: IRPathSegment[] = []
+	const re = /\{([^{}]+)\}/g
+	let last = 0
+	let match: RegExpExecArray | null = re.exec(path)
+	while (match !== null) {
+		if (match.index > last) out.push({ kind: "literal", text: path.slice(last, match.index) })
+		out.push({ kind: "param", name: match[1] })
+		last = match.index + match[0].length
+		match = re.exec(path)
+	}
+	if (last < path.length) out.push({ kind: "literal", text: path.slice(last) })
+	return out
+}
+
+export function openApiPathParams(path: string): string[] {
+	const names: string[] = []
+	for (const seg of parseOpenApiPath(path)) {
+		if (seg.kind === "param" && !names.includes(seg.name)) names.push(seg.name)
+	}
+	return names
+}
+
+type Components = Record<string, Record<string, unknown>>
+
+/** Follows a component `$ref` on a parameter, request body or response object (not on schemas). */
+function deref(value: unknown, components: Components, depth = 0): Record<string, unknown> | undefined {
+	if (!value || typeof value !== "object") return undefined
+	const obj = value as Record<string, unknown>
+	if (typeof obj.$ref !== "string" || depth > 16) return obj
+	const parts = obj.$ref.replace(/^#\//, "").split("/")
+	if (parts[0] !== "components" || parts.length !== 3) return undefined
+	const target = Object.hasOwn(components, parts[1]) ? components[parts[1]] : undefined
+	const next = target && Object.hasOwn(target, parts[2]) ? target[parts[2]] : undefined
+	return deref(next, components, depth + 1)
+}
+
+/** Resolves a top-level schema `$ref` against `components.schemas`, for shape checks only. */
+function resolveSchemaShallow(
+	schema: Record<string, unknown> | undefined,
+	components: Components,
+	depth = 0,
+): Record<string, unknown> | undefined {
+	if (!schema || typeof schema.$ref !== "string" || depth > 16) return schema
+	const name = schema.$ref.split("/").pop() ?? ""
+	const schemas = components.schemas ?? {}
+	const next = Object.hasOwn(schemas, name) ? (schemas[name] as Record<string, unknown>) : undefined
+	return resolveSchemaShallow(next, components, depth + 1)
+}
+
 /** Detect whether a multipart/form-data schema has at least one binary (file) property. */
-function hasBinaryMultipartPart(mediaType: Record<string, unknown> | undefined): boolean {
-	const schema = mediaType?.schema as Record<string, unknown> | undefined
+function hasBinaryMultipartPart(schema: Record<string, unknown> | undefined, components: Components): boolean {
 	const props = schema?.properties as Record<string, Record<string, unknown>> | undefined
 	if (!props) return false
-	for (const prop of Object.values(props)) {
-		if (prop.format === "binary") return true
-		if (prop.type === "array") {
-			const items = prop.items as Record<string, unknown> | undefined
+	for (const raw of Object.values(props)) {
+		const prop = resolveSchemaShallow(raw, components)
+		if (prop?.format === "binary") return true
+		if (prop?.type === "array") {
+			const items = resolveSchemaShallow(prop.items as Record<string, unknown> | undefined, components)
 			if (items?.format === "binary") return true
 		}
 	}
@@ -360,147 +444,369 @@ function hasBinaryMultipartPart(mediaType: Record<string, unknown> | undefined):
 }
 
 /** Normalise a multipart/form-data object schema into typed parts. */
-function extractMultipartParts(mediaType: Record<string, unknown> | undefined): IRMultipartPart[] {
-	const schema = mediaType?.schema as Record<string, unknown> | undefined
+function extractMultipartParts(schema: Record<string, unknown> | undefined, components: Components): IRMultipartPart[] {
 	const props = schema?.properties as Record<string, Record<string, unknown>> | undefined
 	if (!props) return []
 	const parts: IRMultipartPart[] = []
 	for (const [name, propSchema] of Object.entries(props)) {
-		const ir = schemaToIR(propSchema)
-		const isBinary = ir.kind === "binary" || (ir.kind === "array" && ir.items.kind === "binary")
-		parts.push({ name, schema: ir, type: isBinary ? "file" : "text" })
+		const resolved = resolveSchemaShallow(propSchema, components)
+		const resolvedItems =
+			resolved?.type === "array"
+				? resolveSchemaShallow(resolved.items as Record<string, unknown> | undefined, components)
+				: undefined
+		const isBinary = resolved?.format === "binary" || resolvedItems?.format === "binary"
+		parts.push({ name, schema: schemaToIR(propSchema), type: isBinary ? "file" : "text" })
 	}
 	return parts
 }
 
-function buildOperation(id: string, method: string, path: string, op: Record<string, unknown>): IROperation {
+/* JSON first, then the structured kinds, then whatever the spec lists first. */
+const BODY_PREFERENCE = [
+	"application/json",
+	"application/x-www-form-urlencoded",
+	"multipart/form-data",
+	"application/octet-stream",
+]
+
+function isJsonMediaType(ct: string): boolean {
+	const essence = ct.split(";")[0]?.trim().toLowerCase() ?? ""
+	return essence === "application/json" || essence.endsWith("+json")
+}
+
+function contentTypeRank(ct: string): number {
+	const essence = ct.split(";")[0]?.trim().toLowerCase() ?? ""
+	const i = BODY_PREFERENCE.indexOf(essence)
+	if (i >= 0) return i
+	return isJsonMediaType(ct) ? BODY_PREFERENCE.length : BODY_PREFERENCE.length + 1
+}
+
+/** Content types in preference order; ties keep the order the spec lists them in. */
+function orderedContentTypes(content: Record<string, unknown>): string[] {
+	return Object.keys(content)
+		.map((ct, i) => ({ ct, i, rank: contentTypeRank(ct) }))
+		.sort((a, b) => a.rank - b.rank || a.i - b.i)
+		.map((x) => x.ct)
+}
+
+function preferredContentType(content: Record<string, unknown>): string | undefined {
+	return orderedContentTypes(content)[0]
+}
+
+function bodyFor(
+	ct: string,
+	mediaType: Record<string, unknown> | undefined,
+	required: boolean,
+	components: Components,
+): IRBody {
+	const rawSchema = mediaType?.schema as Record<string, unknown> | undefined
+	const essence = ct.split(";")[0]?.trim().toLowerCase()
+	if (essence === "application/octet-stream") {
+		return { contentType: "application/octet-stream", kind: "stream", required }
+	}
+	if (
+		essence === "multipart/form-data" &&
+		hasBinaryMultipartPart(resolveSchemaShallow(rawSchema, components), components)
+	) {
+		const body: IRBody = {
+			contentType: "multipart/form-data",
+			kind: "multipart",
+			parts: extractMultipartParts(resolveSchemaShallow(rawSchema, components), components),
+			required,
+		}
+		if (rawSchema) body.schema = schemaToIR(rawSchema)
+		return body
+	}
+	const bodySchema = rawSchema ? schemaToIR(rawSchema) : { kind: "unknown" as const }
+	return { contentType: ct, kind: "raw", required, schema: bodySchema }
+}
+
+function buildOperation(
+	id: string,
+	method: string,
+	path: string,
+	op: Record<string, unknown>,
+	pathItem: Record<string, unknown>,
+	components: Components,
+): IROperation {
 	const upperMethod = method.toUpperCase()
 
-	const declaredParams = (op.parameters as Record<string, unknown>[] | undefined) ?? []
+	/* path-item parameters apply to every operation unless the operation overrides (same name + in) */
+	const opParams = ((op.parameters as unknown[] | undefined) ?? []).map((p) => deref(p, components))
+	const itemParams = ((pathItem.parameters as unknown[] | undefined) ?? []).map((p) => deref(p, components))
+	const declaredParams: Record<string, unknown>[] = []
+	for (const p of opParams) if (p) declaredParams.push(p)
+	for (const p of itemParams) {
+		if (!p) continue
+		if (!declaredParams.some((d) => d.name === p.name && d.in === p.in)) declaredParams.push(p)
+	}
+
 	const pathParams: IRParam[] = []
 	const queryParams: IRParam[] = []
 	const headerParams: IRParam[] = []
-	const declaredPathNames = new Set<string>()
+	const cookieParams: IRParam[] = []
+	const templateNames = openApiPathParams(path)
 
 	for (const p of declaredParams) {
 		const pIn = p.in as string
-		const pName = p.name as string
+		const pName = String(p.name)
 		const pSchema = p.schema
 			? schemaToIR(p.schema as Record<string, unknown>)
 			: { kind: "scalar" as const, type: "string" as const }
-		const param: IRParam = { name: pName, schema: pSchema }
+		const param: IRParam = { name: pName, required: pIn === "path" || p.required === true, schema: pSchema }
 		if (typeof p.description === "string") param.description = p.description
+		if (p["x-honey-wildcard"] === true) param.wildcard = true
+		const pDefault = (p.schema as Record<string, unknown> | undefined)?.default
+		if (pDefault !== undefined) param.default = pDefault
 		if (pIn === "path") {
-			pathParams.push(param)
-			declaredPathNames.add(pName)
+			/* a declared path param missing from the template cannot be sent */
+			if (templateNames.includes(pName)) pathParams.push(param)
 		} else if (pIn === "query") {
 			queryParams.push(param)
 		} else if (pIn === "header") {
 			headerParams.push(param)
+		} else if (pIn === "cookie") {
+			cookieParams.push(param)
 		}
-		/* cookie params discarded per OpenAPI client convention */
 	}
 
-	/* back-fill path params absent from parameters[] but present in the URL template */
-	for (const name of extractOpenApiPathParams(path)) {
-		if (!declaredPathNames.has(name)) {
-			pathParams.push({ name, schema: { kind: "scalar", type: "string" } })
-		}
+	/* path params in template order; back-fill the ones absent from parameters[] */
+	const orderedPath: IRParam[] = []
+	for (const name of templateNames) {
+		orderedPath.push(
+			pathParams.find((p) => p.name === name) ?? { name, required: true, schema: { kind: "scalar", type: "string" } },
+		)
 	}
 
 	let body: IRBody | undefined
-	const requestBody = op.requestBody as Record<string, unknown> | undefined
+	const bodies: IRBody[] = []
+	const requestBody = deref(op.requestBody, components)
 	if (requestBody) {
 		const content = requestBody.content as Record<string, Record<string, unknown>> | undefined
-		const firstCt = content ? Object.keys(content)[0] : undefined
-		if (firstCt && content) {
-			const mediaType = content[firstCt]
-			const required = requestBody.required === true
-
-			if (firstCt === "application/octet-stream") {
-				body = { contentType: "application/octet-stream", kind: "stream", required }
-			} else if (firstCt === "multipart/form-data" && hasBinaryMultipartPart(mediaType)) {
-				body = {
-					contentType: "multipart/form-data",
-					kind: "multipart",
-					parts: extractMultipartParts(mediaType),
-					required,
-				}
-			} else {
-				const bodySchema = mediaType?.schema
-					? schemaToIR(mediaType.schema as Record<string, unknown>)
-					: { kind: "unknown" as const }
-				body = { contentType: firstCt, kind: "raw", required, schema: bodySchema }
-			}
+		const required = requestBody.required === true
+		for (const ct of content ? orderedContentTypes(content) : []) {
+			bodies.push(bodyFor(ct, content?.[ct], required, components))
 		}
+		body = bodies[0]
 	}
 
 	const responses: Record<string, IRResponse> = {}
 	const extensions: IROperationExtensions = {}
 
-	const rawResponses = op.responses as Record<string, Record<string, unknown>> | undefined
+	const rawResponses = op.responses as Record<string, unknown> | undefined
 	if (rawResponses) {
-		for (const [status, response] of Object.entries(rawResponses)) {
+		for (const [status, rawResponse] of Object.entries(rawResponses)) {
+			const response = deref(rawResponse, components) ?? {}
 			const content = response.content as Record<string, Record<string, unknown>> | undefined
 			if (!content || Object.keys(content).length === 0) {
 				responses[status] = { status }
-			} else {
-				const firstCt = Object.keys(content)[0]
-				/* SSE detected by response content-type, not a request extension */
-				if (firstCt === "text/event-stream") extensions.sse = true
-				const mediaType = content[firstCt]
-				const respSchema = mediaType?.schema ? schemaToIR(mediaType.schema as Record<string, unknown>) : undefined
-				const resp: IRResponse = { contentType: firstCt, status }
-				if (respSchema !== undefined) resp.schema = respSchema
-				responses[status] = resp
+				continue
 			}
+			/* SSE detected by response content-type, not a request extension */
+			if (Object.keys(content).some((k) => k.split(";")[0]?.trim().toLowerCase() === "text/event-stream")) {
+				extensions.sse = true
+			}
+			const ct = preferredContentType(content) ?? Object.keys(content)[0]
+			const mediaType = content[ct]
+			const respSchema = mediaType?.schema ? schemaToIR(mediaType.schema as Record<string, unknown>) : undefined
+			const resp: IRResponse = { contentType: ct, status }
+			if (respSchema !== undefined) resp.schema = respSchema
+			responses[status] = resp
 		}
 	}
 
 	if (op["x-websocket"] === true) extensions.websocket = true
 	if (op["x-realtime"] === true) extensions.realtime = true
-	if (op["x-deprecated"] === true) extensions.deprecated = true
+	if (op["x-deprecated"] === true || op.deprecated === true) extensions.deprecated = true
 	if (op["x-idempotency-key"] === true) extensions.idempotencyKey = true
 	if (op["x-mcp"] === true) extensions.mcp = true
-	if (Array.isArray(op["x-invalidate"])) extensions.invalidates = op["x-invalidate"] as string[]
+	if (Array.isArray(op["x-invalidate"])) {
+		extensions.invalidates = (op["x-invalidate"] as unknown[]).filter((x): x is string => typeof x === "string")
+	}
 
 	const operation: IROperation = {
 		extensions,
 		id,
 		method: upperMethod,
-		params: { header: headerParams, path: pathParams, query: queryParams },
+		params: { header: headerParams, path: orderedPath, query: queryParams },
 		path,
 		responses,
 	}
+	if (cookieParams.length > 0) operation.params.cookie = cookieParams
 	if (body) operation.body = body
+	if (bodies.length > 1) operation.bodies = bodies
 	if (typeof op.description === "string") operation.description = op.description
+	if (typeof op.summary === "string") operation.summary = op.summary
 
 	return operation
 }
 
-export function toIR(spec: OpenApiSpecInput): IR {
-	/* schemas built from raw components BEFORE resolveRefs, which strips them */
+/** Deterministic id for an operation without an `operationId`: `GET /users/{id}` → `getUsersById`. */
+export function deriveOperationId(method: string, path: string): string {
+	const literal: string[] = []
+	const params: string[] = []
+	for (const seg of parseOpenApiPath(path)) {
+		if (seg.kind === "param") params.push(pascalWords(seg.name))
+		else literal.push(pascalWords(seg.text))
+	}
+	const base = `${method.toLowerCase()}${literal.join("")}${params.length > 0 ? `By${params.join("And")}` : ""}`
+	return base === method.toLowerCase() ? `${base}Root` : base
+}
+
+export type ToIROptions = {
+	/** Give operations without an `operationId` a derived one instead of dropping them, and disambiguate
+	 * a shared `operationId` by method. The non-TypeScript SDK emitters use this. */
+	deriveOperationIds?: boolean
+	/** A shared `operationId`: `"suffix"` disambiguates by method (default with `deriveOperationIds`),
+	 * `"throw"` refuses the document (default otherwise; the TypeScript SDK always refuses). */
+	duplicateOperationIds?: "suffix" | "throw"
+}
+
+export function toIR(spec: OpenApiSpecInput, options: ToIROptions = {}): IR {
 	const schemas: Record<string, IRSchema> = {}
 	for (const [name, schema] of Object.entries(spec.components?.schemas ?? {})) {
 		schemas[name] = schemaToIR(schema)
 	}
 
-	const resolved = resolveRefs(spec)
+	const components = (spec.components ?? {}) as Components
 	const operations: IROperation[] = []
 	const seen = new Set<string>()
-
-	for (const [path, pathItem] of Object.entries(resolved.paths)) {
+	const pending: Array<{
+		method: string
+		op: Record<string, unknown>
+		path: string
+		pathItem: Record<string, unknown>
+	}> = []
+
+	for (const [path, pathItem] of Object.entries(spec.paths ?? {})) {
 		for (const method of HTTP_METHODS) {
-			const op = pathItem[method] as Record<string, unknown> | undefined
+			const op = (pathItem as Record<string, unknown>)[method] as Record<string, unknown> | undefined
 			if (!op) continue
 			const id = op.operationId as string | undefined
-			if (!id) continue
-			if (seen.has(id)) throw new Error(`Duplicate operationId: "${id}"`)
-			seen.add(id)
-			operations.push(buildOperation(id, method, path, op))
+			if (!id) {
+				if (options.deriveOperationIds)
+					pending.push({ method, op, path, pathItem: pathItem as Record<string, unknown> })
+				continue
+			}
+			let finalId = id
+			if (seen.has(id)) {
+				const onDuplicate = options.duplicateOperationIds ?? (options.deriveOperationIds ? "suffix" : "throw")
+				if (onDuplicate === "throw") throw new Error(`Duplicate operationId: "${id}"`)
+				finalId = `${id}${pascalWords(method)}`
+				for (let i = 2; seen.has(finalId); i++) finalId = `${id}${pascalWords(method)}${i}`
+			}
+			seen.add(finalId)
+			operations.push(buildOperation(finalId, method, path, op, pathItem as Record<string, unknown>, components))
 		}
 	}
 
+	/* derived ids after explicit ones, so an explicit id always keeps its name */
+	const namespaceRoots = new Set(operations.map((o) => o.id.split(".")[0] ?? o.id))
+	for (const { method, op, path, pathItem } of pending) {
+		const base = deriveOperationId(method, path)
+		let id = base
+		for (let i = 2; seen.has(id) || namespaceRoots.has(id); i++) id = `${base}${i}`
+		seen.add(id)
+		operations.push(buildOperation(id, method, path, op, pathItem, components))
+	}
+
 	const tree = buildResourceTree(operations)
-	return { operations, schemas, tree }
+	const schemaDescriptions: Record<string, string> = {}
+	for (const [name, schema] of Object.entries(spec.components?.schemas ?? {})) {
+		if (typeof schema.description === "string") schemaDescriptions[name] = schema.description
+	}
+	return { auth: specAuth(spec), info: infoOf(spec), operations, schemaDescriptions, schemas, tree }
+}
+
+/**
+ * The first security scheme (code-unit order) decides the header: http basic → `Basic `, other
+ * http → `Bearer `, a header apiKey → its name, with a prefix when its description says
+ * `Format: <prefix> {token}`. Anything else, or no scheme, is `Authorization: Bearer`.
+ */
+export function specAuth(spec: OpenApiSpecInput): IRAuth {
+	const components = (spec.components ?? {}) as Record<string, unknown>
+	const schemes = (components.securitySchemes ?? {}) as Record<string, Record<string, unknown>>
+	const keys = Object.keys(schemes).sort(cmpCodeUnit)
+	const fallback = { headerName: "Authorization", prefix: "Bearer " }
+	const scheme = keys.length > 0 ? schemes[keys[0]] : undefined
+	if (!scheme) return fallback
+	const type = String(scheme.type ?? "")
+	if (type === "http") {
+		const httpScheme = String(scheme.scheme ?? "").toLowerCase()
+		return { headerName: "Authorization", prefix: httpScheme === "basic" ? "Basic " : "Bearer " }
+	}
+	if (type === "apiKey" && scheme.in === "header") {
+		const headerName = String(scheme.name ?? "Authorization")
+		const match = /Format:\s*(\S+)\s+\{/i.exec(String(scheme.description ?? ""))
+		return { headerName, prefix: match ? `${match[1]} ` : "" }
+	}
+	return fallback
+}
+
+function infoOf(spec: OpenApiSpecInput): IRInfo {
+	const info = ((spec as { info?: unknown }).info ?? {}) as Record<string, unknown>
+	const out: IRInfo = {}
+	for (const key of ["title", "description", "version"] as const) {
+		if (typeof info[key] === "string") out[key] = info[key] as string
+	}
+	return out
+}
+
+/** Every request body an operation declares, preferred first. */
+export function bodiesOf(op: IROperation): IRBody[] {
+	return op.bodies ?? (op.body ? [op.body] : [])
+}
+
+/** Follows `ref` nodes to their component schema; an unknown ref resolves to `unknown`. */
+export function irResolver(schemas: Record<string, IRSchema>): (schema: IRSchema) => IRSchema {
+	return (schema) => {
+		let cur = schema
+		for (let i = 0; i < 32 && cur.kind === "ref"; i++) {
+			const next = Object.hasOwn(schemas, cur.name) ? schemas[cur.name] : undefined
+			if (!next) return { kind: "unknown" }
+			cur = next
+		}
+		return cur
+	}
+}
+
+function isStringSchema(s: IRSchema | undefined): boolean {
+	return s?.kind === "scalar" && s.type === "string"
+}
+
+/**
+ * Honey's standard error envelope (`success: false`, `error_key` enum, one `status`), read from the IR.
+ * Returns its error keys and status, or null for any other shape.
+ */
+export function irErrorEnvelope(
+	schema: IRSchema,
+	resolve: (schema: IRSchema) => IRSchema,
+): { keys: string[]; status: number } | null {
+	const obj = resolve(schema)
+	if (obj.kind !== "object") return null
+	const field = (o: Extract<IRSchema, { kind: "object" }>, name: string): IRSchema | undefined => {
+		const f = o.fields.find((x) => x.name === name)
+		return f ? resolve(f.schema) : undefined
+	}
+
+	const success = field(obj, "success")
+	if (success?.kind !== "const" || success.value !== false) return null
+	if (!isStringSchema(field(obj, "message")) || !isStringSchema(field(obj, "status_key"))) return null
+
+	const fields = field(obj, "fields")
+	if (fields?.kind !== "object" || !fields.additional) return null
+	const list = resolve(fields.additional)
+	if (list.kind !== "array") return null
+	const item = resolve(list.items)
+	if (item.kind !== "object") return null
+	for (const k of ["error_key", "message", "path"]) if (!isStringSchema(field(item, k))) return null
+
+	const status = field(obj, "status")
+	if (status?.kind !== "scalar" || !status.enum || status.enum.length !== 1) return null
+	const statusVal = status.enum[0]
+	if (typeof statusVal !== "number") return null
+
+	const key = field(obj, "error_key")
+	if (key?.kind !== "scalar" || !key.enum || key.enum.length === 0) return null
+	if (!key.enum.every((k) => typeof k === "string")) return null
+	return { keys: key.enum as string[], status: statusVal }
 }