schema-components 1.20.0 → 1.22.0

package/dist/openapi/components.mjs

@@ -1,12 +1,13 @@
 import { isObject, toRecordOrUndefined } from "../core/guards.mjs";
+import { emitDiagnostic } from "../core/diagnostics.mjs";
 import { walk } from "../core/walker.mjs";
 import { ApiCallbacks } from "./ApiCallbacks.mjs";
 import { ApiLinks } from "./ApiLinks.mjs";
 import { ApiResponseHeaders } from "./ApiResponseHeaders.mjs";
 import { ApiSecurity } from "./ApiSecurity.mjs";
-import { getLinks, getSecurityRequirements, getSecuritySchemes, listCallbacks } from "./parser.mjs";
+import { getExternalDocs, getLinks, getSecurityRequirements, getSecuritySchemes, getXmlInfo, listCallbacks, listWebhooks } from "./parser.mjs";
 import { joinPath, renderField, sanitisePrefix } from "../react/SchemaComponent.mjs";
-import { getParsed, resolveOperation, resolveParameters, resolveRequestBody, resolveResponse, toDoc } from "./resolve.mjs";
+import { getParsed, resolveOperationFromParsed, resolveParametersFromParsed, resolveRequestBodyFromParsed, resolveResponseFromParsed, toDoc } from "./resolve.mjs";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useId } from "react";
 //#region src/openapi/components.tsx
@@ -23,6 +24,32 @@ import { useId } from "react";
 * rendered via the walker + headless resolver directly, bypassing
 * SchemaComponent to avoid deferred-conditional-type compatibility issues.
 */
+function buildDiagnostics(onDiagnostic, strict) {
+	if (onDiagnostic === void 0 && strict !== true) return void 0;
+	const opts = {};
+	if (onDiagnostic !== void 0) opts.diagnostics = onDiagnostic;
+	if (strict === true) opts.strict = true;
+	return opts;
+}
+/**
+* Coerce an `unknown` `schema` prop to a document record. Returns
+* `undefined` when the prop is not a plain object, surfacing a
+* `doc-not-object` diagnostic so silent "empty document" misbehaviour
+* (the historic `toDoc` `{}` fallback) is impossible.
+*
+* Components MUST short-circuit when this returns `undefined` rather
+* than rendering empty operation lists.
+*/
+function resolveRootDoc(doc, diagnostics) {
+	const resolved = toDoc(doc);
+	if (resolved === void 0) emitDiagnostic(diagnostics, {
+		code: "doc-not-object",
+		message: "OpenAPI document prop is not a plain object; nothing to render",
+		pointer: "",
+		detail: { received: typeof doc }
+	});
+	return resolved;
+}
 function noop() {}
 function renderSchema(schema, rootDocument, options) {
 	if (!isObject(schema)) throw new Error("renderSchema received a non-object schema from the resolver.");
@@ -42,14 +69,55 @@ function renderSchema(schema, rootDocument, options) {
 	};
 	return renderField(tree, options.value, options.onChange ?? noop, void 0, makeRenderChild(options.rootPath), options.rootPath, options.widgets);
 }
-function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBodyChange, responseValue, meta, requestBodyFields, widgets }) {
-	const rootDoc = toDoc(doc);
-	const resolved = resolveOperation(rootDoc, path, method);
-	const parsed = getParsed(rootDoc);
+/**
+* Render a Schema Object or Operation Object's `externalDocs` as a
+* simple anchor with optional descriptive text. Returns `null` when no
+* externalDocs are attached so callers can drop it into JSX without an
+* extra guard.
+*/
+function ExternalDocsLink({ externalDocs }) {
+	if (externalDocs === void 0) return null;
+	return /* @__PURE__ */ jsx("p", {
+		"data-external-docs": true,
+		children: /* @__PURE__ */ jsx("a", {
+			href: externalDocs.url,
+			children: externalDocs.description ?? externalDocs.url
+		})
+	});
+}
+/**
+* Render a Schema Object's `xml` metadata as a footnote. The library
+* does not render XML payloads natively, but the metadata still
+* carries author intent (namespaces, element names, wrapping rules).
+* Surface it so consumers can audit the dropped feature without
+* losing the underlying information.
+*/
+function SchemaXmlFootnote({ xml }) {
+	if (xml === void 0) return null;
+	return /* @__PURE__ */ jsx("aside", {
+		"data-schema-xml": true,
+		children: /* @__PURE__ */ jsxs("small", { children: [
+			"XML representation",
+			xml.name !== void 0 && ` — name: ${xml.name}`,
+			xml.namespace !== void 0 && ` — namespace: ${xml.namespace}`,
+			xml.prefix !== void 0 && ` — prefix: ${xml.prefix}`,
+			xml.attribute && " — attribute",
+			xml.wrapped && " — wrapped"
+		] })
+	});
+}
+function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBodyChange, responseValue, meta, requestBodyFields, widgets, onDiagnostic, strict }) {
+	const diagnostics = buildDiagnostics(onDiagnostic, strict);
+	const instancePrefix = sanitisePrefix(useId());
+	const rootDoc = resolveRootDoc(doc, diagnostics);
+	if (rootDoc === void 0) return null;
+	const parsed = getParsed(rootDoc, diagnostics);
+	const resolved = resolveOperationFromParsed(parsed, path, method, diagnostics);
 	const securityReqs = getSecurityRequirements(parsed, path, method);
 	const securitySchemes = getSecuritySchemes(parsed);
 	const callbacks = listCallbacks(parsed, path, method);
-	const instancePrefix = sanitisePrefix(useId());
+	const operationExternalDocs = getExternalDocs(resolved.operation.operation);
+	const requestBodyXml = resolved.requestBody?.schema !== void 0 ? getXmlInfo(resolved.requestBody.schema) : void 0;
 	return /* @__PURE__ */ jsxs("section", {
 		"data-operation": `${method.toUpperCase()} ${path}`,
 		children: [
@@ -57,6 +125,7 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 				operation: resolved.operation,
 				pathItem: resolved.pathItem
 			}),
+			/* @__PURE__ */ jsx(ExternalDocsLink, { externalDocs: operationExternalDocs }),
 			/* @__PURE__ */ jsx(ApiSecurity, {
 				requirements: securityReqs,
 				schemes: securitySchemes
@@ -91,7 +160,8 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 						meta,
 						widgets,
 						rootPath: joinPath(instancePrefix, "requestBody")
-					})
+					}),
+					/* @__PURE__ */ jsx(SchemaXmlFootnote, { xml: requestBodyXml })
 				]
 			}),
 			resolved.responses.length > 0 && /* @__PURE__ */ jsxs("section", {
@@ -99,6 +169,7 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 				children: [/* @__PURE__ */ jsx("h4", { children: "Responses" }), resolved.responses.map((response) => /* @__PURE__ */ jsx(ResponseCard, {
 					response,
 					rootDoc,
+					parsed,
 					value: responseValue,
 					meta,
 					widgets,
@@ -110,10 +181,12 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 		]
 	});
 }
-function ApiParameters({ schema: doc, path, method, meta, overrides, widgets }) {
-	const rootDoc = toDoc(doc);
-	const params = resolveParameters(rootDoc, path, method);
+function ApiParameters({ schema: doc, path, method, meta, overrides, widgets, onDiagnostic, strict }) {
+	const diagnostics = buildDiagnostics(onDiagnostic, strict);
 	const instancePrefix = sanitisePrefix(useId());
+	const rootDoc = resolveRootDoc(doc, diagnostics);
+	if (rootDoc === void 0) return null;
+	const params = resolveParametersFromParsed(getParsed(rootDoc, diagnostics), path, method);
 	if (params.length === 0) return null;
 	return /* @__PURE__ */ jsxs("section", {
 		"data-parameters": true,
@@ -127,11 +200,14 @@ function ApiParameters({ schema: doc, path, method, meta, overrides, widgets })
 		})]
 	});
 }
-function ApiRequestBody({ schema: doc, path, method, value, onChange, meta, fields, widgets }) {
-	const rootDoc = toDoc(doc);
-	const requestBody = resolveRequestBody(rootDoc, path, method);
+function ApiRequestBody({ schema: doc, path, method, value, onChange, meta, fields, widgets, onDiagnostic, strict }) {
+	const diagnostics = buildDiagnostics(onDiagnostic, strict);
 	const instancePrefix = sanitisePrefix(useId());
+	const rootDoc = resolveRootDoc(doc, diagnostics);
+	if (rootDoc === void 0) return null;
+	const requestBody = resolveRequestBodyFromParsed(getParsed(rootDoc, diagnostics), path, method);
 	if (requestBody?.schema === void 0) return null;
+	const requestBodyXml = getXmlInfo(requestBody.schema);
 	return /* @__PURE__ */ jsxs("section", {
 		"data-request-body": true,
 		children: [
@@ -151,14 +227,18 @@ function ApiRequestBody({ schema: doc, path, method, value, onChange, meta, fiel
 				meta,
 				widgets,
 				rootPath: instancePrefix
-			})
+			}),
+			/* @__PURE__ */ jsx(SchemaXmlFootnote, { xml: requestBodyXml })
 		]
 	});
 }
-function ApiResponse({ schema: doc, path, method, status, value, meta, fields, widgets }) {
-	const rootDoc = toDoc(doc);
-	const response = resolveResponse(rootDoc, path, method, status);
+function ApiResponse({ schema: doc, path, method, status, value, meta, fields, widgets, onDiagnostic, strict }) {
+	const diagnostics = buildDiagnostics(onDiagnostic, strict);
 	const instancePrefix = sanitisePrefix(useId());
+	const rootDoc = resolveRootDoc(doc, diagnostics);
+	if (rootDoc === void 0) return null;
+	const parsed = getParsed(rootDoc, diagnostics);
+	const response = resolveResponseFromParsed(parsed, path, method, status);
 	if (response.schema === void 0) return /* @__PURE__ */ jsxs("div", {
 		"data-status": status,
 		children: [
@@ -170,6 +250,7 @@ function ApiResponse({ schema: doc, path, method, status, value, meta, fields, w
 	return /* @__PURE__ */ jsx(ResponseCard, {
 		response,
 		rootDoc,
+		parsed,
 		value,
 		fields,
 		meta,
@@ -179,6 +260,49 @@ function ApiResponse({ schema: doc, path, method, status, value, meta, fields, w
 		idPrefix: instancePrefix
 	});
 }
+function ApiWebhook({ schema: doc, name, widgets, meta, onDiagnostic, strict }) {
+	const diagnostics = buildDiagnostics(onDiagnostic, strict);
+	const instancePrefix = sanitisePrefix(useId());
+	const rootDoc = resolveRootDoc(doc, diagnostics);
+	if (rootDoc === void 0) return null;
+	const webhook = listWebhooks(getParsed(rootDoc, diagnostics)).find((w) => w.name === name);
+	if (webhook === void 0) return null;
+	return /* @__PURE__ */ jsxs("section", {
+		"data-webhook": name,
+		"data-instance": instancePrefix,
+		children: [/* @__PURE__ */ jsxs("h3", { children: ["Webhook: ", name] }), webhook.operations.map((op) => {
+			const opProps = {
+				schema: rootDoc,
+				path: name,
+				method: op.method
+			};
+			if (widgets !== void 0) opProps.widgets = widgets;
+			if (meta !== void 0) opProps.meta = meta;
+			return /* @__PURE__ */ jsx(ApiOperation, { ...opProps }, `${name}-${op.method}`);
+		})]
+	});
+}
+function ApiWebhooks({ schema: doc, widgets, meta, onDiagnostic, strict }) {
+	const diagnostics = buildDiagnostics(onDiagnostic, strict);
+	const instancePrefix = sanitisePrefix(useId());
+	const rootDoc = resolveRootDoc(doc, diagnostics);
+	if (rootDoc === void 0) return null;
+	const webhooks = listWebhooks(getParsed(rootDoc, diagnostics));
+	if (webhooks.length === 0) return null;
+	return /* @__PURE__ */ jsxs("section", {
+		"data-webhooks": true,
+		"data-instance": instancePrefix,
+		children: [/* @__PURE__ */ jsx("h2", { children: "Webhooks" }), webhooks.map((webhook) => {
+			const props = {
+				schema: rootDoc,
+				name: webhook.name
+			};
+			if (widgets !== void 0) props.widgets = widgets;
+			if (meta !== void 0) props.meta = meta;
+			return /* @__PURE__ */ jsx(ApiWebhook, { ...props }, webhook.name);
+		})]
+	});
+}
 function OperationHeader({ operation, pathItem }) {
 	return /* @__PURE__ */ jsxs("header", { children: [
 		(pathItem.summary !== void 0 || pathItem.description !== void 0) && /* @__PURE__ */ jsxs("div", {
@@ -227,7 +351,7 @@ function ParameterList({ parameters, rootDoc, overrides, meta, widgets, idPrefix
 		]
 	}, param.name)) });
 }
-function ResponseCard({ response, rootDoc, value, fields, meta, widgets, path, method, idPrefix }) {
+function ResponseCard({ response, rootDoc, parsed, value, fields, meta, widgets, path, method, idPrefix }) {
 	if (response.schema === void 0) return /* @__PURE__ */ jsxs("div", {
 		"data-status": response.statusCode,
 		children: [
@@ -237,7 +361,7 @@ function ResponseCard({ response, rootDoc, value, fields, meta, widgets, path, m
 		]
 	});
 	let links = [];
-	if (path !== void 0 && method !== void 0) links = getLinks(getParsed(rootDoc), path, method, response.statusCode);
+	if (path !== void 0 && method !== void 0) links = getLinks(parsed, path, method, response.statusCode);
 	return /* @__PURE__ */ jsxs("div", {
 		"data-status": response.statusCode,
 		children: [
@@ -283,4 +407,4 @@ function extractRootMetaFromSchema(jsonSchema) {
 	return Object.keys(meta).length > 0 ? meta : void 0;
 }
 //#endregion
-export { ApiOperation, ApiParameters, ApiRequestBody, ApiResponse };
+export { ApiOperation, ApiParameters, ApiRequestBody, ApiResponse, ApiWebhook, ApiWebhooks };

package/dist/openapi/parser.d.mts

@@ -1,4 +1,4 @@
-import { m as JsonObject } from "../types-C9zw9wbX.mjs";
+import { m as JsonObject } from "../types-BrRMV0en.mjs";
 
 //#region src/openapi/parser.d.ts
 interface OpenApiDocument {

package/dist/openapi/parser.mjs

@@ -1,4 +1,5 @@
 import { getProperty, isObject } from "../core/guards.mjs";
+import "../core/limits.mjs";
 import { isPrototypePollutingKey } from "../core/uri.mjs";
 //#region src/openapi/parser.ts
 function getString(value, key) {
@@ -44,11 +45,27 @@ const METHODS = [
 * (OpenAPI 3.1) if present. Returns `undefined` when the value is not a
 * path item, the ref is malformed, or the target does not resolve.
 */
+/**
+* Follow Path Item Object `$ref` chains (up to MAX_PATH_ITEM_REF_HOPS).
+* Returns the resolved Path Item, or `undefined` when the chain cycles,
+* exceeds the cap, or any intermediate ref fails to resolve. The
+* detailed diagnostics for cycle and depth-cap are emitted by the
+* mirroring resolver in `resolve.ts` — this parser-side resolver simply
+* stops walking.
+*/
 function resolvePathItem(parsed, pathItem) {
 	if (!isObject(pathItem)) return void 0;
-	const ref = getString(pathItem, "$ref");
-	if (ref === void 0) return pathItem;
-	return resolveRefInDoc(parsed.doc, ref) ?? void 0;
+	const visited = /* @__PURE__ */ new Set();
+	let current = pathItem;
+	for (let hop = 0; hop < 8; hop++) {
+		const ref = getString(current, "$ref");
+		if (ref === void 0) return current;
+		if (visited.has(ref)) return void 0;
+		visited.add(ref);
+		const target = resolveRefInDoc(parsed.doc, ref);
+		if (target === void 0) return void 0;
+		current = target;
+	}
 }
 function lookupPathItem(parsed, path) {
 	const resolved = resolvePathItem(parsed, getProperty(getProperty(parsed.doc, "paths"), path));
@@ -120,8 +137,10 @@ function resolveParam(doc, param) {
 	return param;
 }
 function getRequestBody(parsed, path, method) {
-	const requestBody = getProperty(getProperty(lookupPathItem(parsed, path), method), "requestBody");
-	if (!isObject(requestBody)) return void 0;
+	const requestBodyRaw = getProperty(getProperty(lookupPathItem(parsed, path), method), "requestBody");
+	if (!isObject(requestBodyRaw)) return void 0;
+	const requestBody = resolveWrapperRef(parsed.doc, requestBodyRaw);
+	if (requestBody === void 0) return void 0;
 	const content = getProperty(requestBody, "content");
 	if (!isObject(content)) return {
 		required: getProperty(requestBody, "required") === true,
@@ -142,8 +161,10 @@ function getResponses(parsed, path, method) {
 	const responses = getProperty(getProperty(lookupPathItem(parsed, path), method), "responses");
 	if (!isObject(responses)) return [];
 	const result = [];
-	for (const [statusCode, response] of Object.entries(responses)) {
-		if (!isObject(response)) continue;
+	for (const [statusCode, responseRaw] of Object.entries(responses)) {
+		if (!isObject(responseRaw)) continue;
+		const response = resolveWrapperRef(parsed.doc, responseRaw);
+		if (response === void 0) continue;
 		const content = getProperty(response, "content");
 		const contentTypes = isObject(content) ? Object.keys(content) : [];
 		const schema = isObject(content) ? extractSchemaFromContent(content) : void 0;
@@ -158,15 +179,61 @@ function getResponses(parsed, path, method) {
 	}
 	return result;
 }
+/**
+* Resolve a single-hop `$ref` on a wrapper object — Response Object,
+* Request Body Object, etc. — against the document root. Returns the
+* referenced node when the wrapper is a `$ref`, the wrapper itself when
+* it has no `$ref`, or `undefined` when the `$ref` is malformed or
+* cannot be resolved (so the caller skips the entry rather than reading
+* stale fields from the bare `{ $ref }` envelope).
+*/
+function resolveWrapperRef(doc, wrapper) {
+	const ref = getString(wrapper, "$ref");
+	if (ref === void 0) return wrapper;
+	return resolveRefInDoc(doc, ref);
+}
 function extractSchemaFromContent(content) {
 	const jsonSchema = getProperty(getProperty(content, "application/json"), "schema");
 	if (isObject(jsonSchema)) return jsonSchema;
+	for (const [mediaType, mediaObj] of Object.entries(content)) {
+		if (!isJsonSuffixMediaType(mediaType)) continue;
+		if (!isObject(mediaObj)) continue;
+		const schema = getProperty(mediaObj, "schema");
+		if (isObject(schema)) return schema;
+	}
 	for (const mediaType of Object.values(content)) {
 		if (!isObject(mediaType)) continue;
 		const schema = getProperty(mediaType, "schema");
 		if (isObject(schema)) return schema;
 	}
 }
+/**
+* Detect RFC 6839 structured-syntax-suffix media types that encode JSON.
+* Matches `application/<anything>+json`, optionally with parameters
+* (`; charset=utf-8`). Excludes the literal `application/json`, which
+* the caller checks separately to preserve preference order.
+*/
+function isJsonSuffixMediaType(mediaType) {
+	const lower = mediaType.toLowerCase();
+	if (lower === "application/json") return false;
+	const baseType = lower.split(";", 1)[0]?.trim() ?? "";
+	return baseType.startsWith("application/") && baseType.endsWith("+json");
+}
+/**
+* Resolve an in-document `$ref` against the supplied doc root.
+*
+* Limitation — cross-Schema-Object relative refs: refs that do NOT
+* start with `#/` are not resolved here. The `normaliseOpenApiSchemas`
+* pipeline (see `resolveRelativeRefs` in `core/normalise.ts`) rewrites
+* relative refs WITHIN a Schema Object using that schema's `$id` base
+* URI, but it does not currently model `$id` scopes that span Schema
+* Object boundaries (e.g. a sibling component schema with its own
+* `$id` that another schema's relative ref targets). Such refs survive
+* normalisation unchanged and fall through this function returning
+* `undefined`. `resolve.ts:detectUnsupportedCrossSchemaRefs` walks the
+* normalised doc and emits `cross-schema-relative-ref-unsupported` per
+* offending ref so consumers notice the silent failure.
+*/
 function resolveRefInDoc(doc, ref) {
 	if (!ref.startsWith("#/")) return void 0;
 	const parts = ref.slice(2).split("/");

package/dist/openapi/resolve.d.mts

@@ -1,3 +1,4 @@
+import { i as DiagnosticsOptions } from "../diagnostics-D0QCYGv0.mjs";
 import { OpenApiDocument, OperationInfo, ParameterInfo, ResponseInfo, getRequestBody } from "./parser.mjs";
 
 //#region src/openapi/resolve.d.ts
@@ -14,15 +15,31 @@ import { OpenApiDocument, OperationInfo, ParameterInfo, ResponseInfo, getRequest
  * same form `<SchemaComponent>` does, keeping the OpenAPI components on
  * the same pipeline as the top-level adapter.
  *
- * The cache is keyed by the caller-supplied document so subsequent calls
- * with the same input bypass both normalisation and parsing.
+ * When `diagnostics` is supplied, normalisation events
+ * (`duplicate-body-parameter`, `dropped-swagger-feature`,
+ * `unknown-json-schema-dialect`, `divisible-by-conflict`,
+ * `relative-ref-resolved`, etc.) are forwarded to the sink. Passing
+ * diagnostics also bypasses the cache so each call observes the
+ * normalisation pipeline running against the supplied sink — caching
+ * would silently swallow every emission after the first.
+ *
+ * The cache is keyed by the caller-supplied document so subsequent
+ * cache-eligible calls with the same input bypass both normalisation
+ * and parsing.
  */
-declare function getParsed(doc: Record<string, unknown>): OpenApiDocument;
+declare function getParsed(doc: Record<string, unknown>, diagnostics?: DiagnosticsOptions): OpenApiDocument;
 /**
- * Coerce an unknown value to a record, returning an empty record
- * for non-objects.
+ * Coerce an unknown value to a record, returning `undefined` when the
+ * value is not a plain object. Callers MUST handle the `undefined` case
+ * explicitly — typically by rendering a "doc not an object" diagnostic
+ * and short-circuiting, never by silently substituting `{}`.
+ *
+ * A previous implementation fell back to `{}` for non-objects, which
+ * masked configuration mistakes (passing a string, `null`, an array, or
+ * `undefined` as the OpenAPI document) as an empty document with no
+ * operations.
  */
-declare function toDoc(value: unknown): Record<string, unknown>;
+declare function toDoc(value: unknown): Record<string, unknown> | undefined;
 /**
  * Path-Item-level metadata. OpenAPI 3.1 added `summary` and `description`
  * to Path Item Objects alongside the existing operation-level fields.
@@ -39,26 +56,67 @@ interface ResolvedOperation {
   requestBody: ReturnType<typeof getRequestBody>;
   responses: ResponseInfo[];
 }
+/**
+ * Resolve an operation against an already-parsed document. Throws if
+ * the operation is not found.
+ *
+ * Used by callers that have already obtained a parsed document via
+ * {@link getParsed} — most importantly the React components, which
+ * supply `diagnostics` to `getParsed` and must avoid re-running the
+ * normalisation pipeline (every re-run would emit each diagnostic
+ * again into the sink).
+ */
+declare function resolveOperationFromParsed(parsed: OpenApiDocument, path: string, method: string, diagnostics?: DiagnosticsOptions): ResolvedOperation;
 /**
  * Resolve an operation from an OpenAPI document by path and method.
  * Throws if the operation is not found.
+ *
+ * `diagnostics` is forwarded to {@link getParsed} so normalisation
+ * events surface to the caller's sink.
+ */
+declare function resolveOperation(doc: Record<string, unknown>, path: string, method: string, diagnostics?: DiagnosticsOptions): ResolvedOperation;
+/**
+ * Resolve parameters against an already-parsed document. See
+ * {@link resolveOperationFromParsed} for the rationale.
  */
-declare function resolveOperation(doc: Record<string, unknown>, path: string, method: string): ResolvedOperation;
+declare function resolveParametersFromParsed(parsed: OpenApiDocument, path: string, method: string): ParameterInfo[];
 /**
  * Resolve parameters for an operation. Returns empty array if none.
+ *
+ * `diagnostics` is forwarded to {@link getParsed} so normalisation
+ * events surface to the caller's sink.
+ */
+declare function resolveParameters(doc: Record<string, unknown>, path: string, method: string, diagnostics?: DiagnosticsOptions): ParameterInfo[];
+/**
+ * Resolve a request body against an already-parsed document. See
+ * {@link resolveOperationFromParsed} for the rationale.
  */
-declare function resolveParameters(doc: Record<string, unknown>, path: string, method: string): ParameterInfo[];
+declare function resolveRequestBodyFromParsed(parsed: OpenApiDocument, path: string, method: string): ReturnType<typeof getRequestBody>;
 /**
  * Resolve request body for an operation. Returns undefined if none.
+ *
+ * `diagnostics` is forwarded to {@link getParsed} so normalisation
+ * events surface to the caller's sink.
  */
-declare function resolveRequestBody(doc: Record<string, unknown>, path: string, method: string): ReturnType<typeof getRequestBody>;
+declare function resolveRequestBody(doc: Record<string, unknown>, path: string, method: string, diagnostics?: DiagnosticsOptions): ReturnType<typeof getRequestBody>;
+/**
+ * Resolve a specific response against an already-parsed document. See
+ * {@link resolveOperationFromParsed} for the rationale.
+ */
+declare function resolveResponseFromParsed(parsed: OpenApiDocument, path: string, method: string, statusCode: string): ResponseInfo;
 /**
  * Resolve a specific response by status code. Throws if not found.
+ *
+ * `diagnostics` is forwarded to {@link getParsed} so normalisation
+ * events surface to the caller's sink.
  */
-declare function resolveResponse(doc: Record<string, unknown>, path: string, method: string, statusCode: string): ResponseInfo;
+declare function resolveResponse(doc: Record<string, unknown>, path: string, method: string, statusCode: string, diagnostics?: DiagnosticsOptions): ResponseInfo;
 /**
  * Resolve all responses for an operation.
+ *
+ * `diagnostics` is forwarded to {@link getParsed} so normalisation
+ * events surface to the caller's sink.
  */
-declare function resolveResponses(doc: Record<string, unknown>, path: string, method: string): ResponseInfo[];
+declare function resolveResponses(doc: Record<string, unknown>, path: string, method: string, diagnostics?: DiagnosticsOptions): ResponseInfo[];
 //#endregion
-export { PathItemInfo, ResolvedOperation, getParsed, resolveOperation, resolveParameters, resolveRequestBody, resolveResponse, resolveResponses, toDoc };
+export { PathItemInfo, ResolvedOperation, getParsed, resolveOperation, resolveOperationFromParsed, resolveParameters, resolveParametersFromParsed, resolveRequestBody, resolveRequestBodyFromParsed, resolveResponse, resolveResponseFromParsed, resolveResponses, toDoc };