schema-components 1.22.0 → 1.24.0

package/dist/openapi/parser.mjs

@@ -1,14 +1,37 @@
 import { getProperty, isObject } from "../core/guards.mjs";
 import "../core/limits.mjs";
+import { emitDiagnostic } from "../core/diagnostics.mjs";
 import { isPrototypePollutingKey } from "../core/uri.mjs";
+import { detectOpenApiVersion } from "../core/version.mjs";
+import { HTTP_METHODS } from "../core/openapiConstants.mjs";
+import { resolveRefChain } from "../core/refChain.mjs";
 //#region src/openapi/parser.ts
 function getString(value, key) {
 	const result = isObject(value) ? value[key] : void 0;
 	return typeof result === "string" ? result : void 0;
 }
-function toParameterLocation(value) {
+/**
+* Narrow an OpenAPI parameter `in` value to the canonical four-value
+* `ParameterLocation` union. Returns `undefined` for any other value
+* (including the Swagger 2.0 `body`/`formData` locations, which the
+* Swagger 2.0 → OpenAPI 3.x normaliser is expected to have already
+* lifted out of the parameter array). When `diagnostics` is supplied,
+* emits an `unknown-parameter-location` diagnostic so the caller can
+* audit silent drops; without a sink the function still returns
+* `undefined` rather than coercing the value, so the parameter is
+* excluded from the operation's parameter list either way.
+*/
+function toParameterLocation(value, parameterName, pointer, diagnostics) {
 	if (value === "query" || value === "path" || value === "header" || value === "cookie") return value;
-	return "query";
+	emitDiagnostic(diagnostics, {
+		code: "unknown-parameter-location",
+		message: parameterName !== void 0 ? `Parameter "${parameterName}" declares unknown \`in\` value ${JSON.stringify(value)}; expected one of query, path, header, cookie` : `Parameter declares unknown \`in\` value ${JSON.stringify(value)}; expected one of query, path, header, cookie`,
+		pointer,
+		detail: {
+			name: parameterName,
+			in: value
+		}
+	});
 }
 function parseOpenApiDocument(doc) {
 	const schemas = /* @__PURE__ */ new Map();
@@ -30,62 +53,94 @@ function getSchema(parsed, ref) {
 		return resolved;
 	}
 }
-const METHODS = [
-	"get",
-	"post",
-	"put",
-	"patch",
-	"delete",
-	"head",
-	"options",
-	"trace"
-];
-/**
-* Resolve a path item, following a `$ref` to `components/pathItems/<Name>`
-* (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.
+* exceeds the cap, or any intermediate ref fails to resolve.
+*
+* When `diagnostics` is supplied, cycle and depth-cap conditions emit
+* `cyclic-path-item-ref` and `path-item-ref-too-deep` respectively. When
+* `diagnostics` is omitted, the resolver still rejects cycles and
+* over-deep chains silently — callers that wire their own resolver
+* (notably `resolve.ts:resolvePathItemNode`) supply diagnostics to
+* mirror this behaviour with full pointer information.
 */
-function resolvePathItem(parsed, pathItem) {
+function resolvePathItem(parsed, pathItem, diagnostics) {
 	if (!isObject(pathItem)) return 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;
-	}
+	return resolveRefChain(pathItem, {
+		lookup: (ref) => ref.startsWith("#/") ? resolveRefInDoc(parsed.doc, ref) : void 0,
+		maxHops: 8,
+		onCycle: (ref) => {
+			emitDiagnostic(diagnostics, {
+				code: "cyclic-path-item-ref",
+				message: `Cyclic Path Item Object $ref "${ref}"`,
+				pointer: ref,
+				detail: { ref }
+			});
+		},
+		onDepthExceeded: (ref) => {
+			emitDiagnostic(diagnostics, {
+				code: "path-item-ref-too-deep",
+				message: `Path Item Object $ref chain exceeded ${String(8)} hops`,
+				pointer: ref,
+				detail: {
+					maxHops: 8,
+					ref
+				}
+			});
+		}
+	});
 }
 function lookupPathItem(parsed, path) {
 	const resolved = resolvePathItem(parsed, getProperty(getProperty(parsed.doc, "paths"), path));
 	if (resolved !== void 0) return resolved;
 	return resolvePathItem(parsed, getProperty(getProperty(parsed.doc, "webhooks"), path));
 }
-function listOperations(parsed) {
+/**
+* Record an `operationId` against a shared `seenIds` map and emit a
+* `duplicate-operation-id` diagnostic when a subsequent location reuses
+* the same identifier. Returns the original `operationId` so the caller
+* can pass the value straight onto its `OperationInfo`.
+*
+* When the same map is threaded through `listOperations` and
+* `listWebhooks` (see `listAllOperations`), cross-list collisions
+* between a path operation and a webhook operation surface as the same
+* diagnostic class as same-list collisions.
+*/
+function recordOperationId(operationId, location, pointer, seenIds, diagnostics) {
+	if (operationId === void 0) return;
+	const firstSeenAt = seenIds.get(operationId);
+	if (firstSeenAt !== void 0) {
+		emitDiagnostic(diagnostics, {
+			code: "duplicate-operation-id",
+			message: `operationId "${operationId}" is declared more than once (first at ${firstSeenAt}, again at ${location})`,
+			pointer,
+			detail: {
+				operationId,
+				firstSeenAt,
+				duplicateAt: location
+			}
+		});
+		return;
+	}
+	seenIds.set(operationId, location);
+}
+function listOperations(parsed, diagnostics, seenIds = /* @__PURE__ */ new Map()) {
 	const operations = [];
 	const paths = getProperty(parsed.doc, "paths");
 	if (!isObject(paths)) return operations;
 	for (const [path, rawPathItem] of Object.entries(paths)) {
-		const pathItem = resolvePathItem(parsed, rawPathItem);
+		const pathItem = resolvePathItem(parsed, rawPathItem, diagnostics);
 		if (pathItem === void 0) continue;
-		for (const method of METHODS) {
+		for (const method of HTTP_METHODS) {
 			const operation = getProperty(pathItem, method);
 			if (!isObject(operation)) continue;
+			const operationId = getString(operation, "operationId");
+			recordOperationId(operationId, `${method.toUpperCase()} ${path}`, `/paths/${jsonPointerEscape(path)}/${method}/operationId`, seenIds, diagnostics);
 			operations.push({
 				path,
 				method,
-				operationId: getString(operation, "operationId"),
+				operationId,
 				summary: getString(operation, "summary"),
 				description: getString(operation, "description"),
 				deprecated: getProperty(operation, "deprecated") === true,
@@ -95,31 +150,35 @@ function listOperations(parsed) {
 	}
 	return operations;
 }
-function getParameters(parsed, path, method) {
+function getParameters(parsed, path, method, diagnostics) {
 	const pathItem = lookupPathItem(parsed, path);
 	if (pathItem === void 0) return [];
 	const operation = getProperty(pathItem, method);
 	if (!isObject(operation)) return [];
-	const pathParams = extractParameterList(parsed.doc, getProperty(pathItem, "parameters"));
-	const opParams = extractParameterList(parsed.doc, getProperty(operation, "parameters"));
+	const pathParams = extractParameterList(parsed.doc, getProperty(pathItem, "parameters"), `/paths/${jsonPointerEscape(path)}/parameters`, diagnostics);
+	const opParams = extractParameterList(parsed.doc, getProperty(operation, "parameters"), `/paths/${jsonPointerEscape(path)}/${method}/parameters`, diagnostics);
 	const map = /* @__PURE__ */ new Map();
 	for (const param of pathParams) map.set(`${param.name}:${param.location}`, param);
 	for (const param of opParams) map.set(`${param.name}:${param.location}`, param);
 	return [...map.values()];
 }
-function extractParameterList(doc, parameters) {
+function extractParameterList(doc, parameters, pointerBase, diagnostics) {
 	if (!Array.isArray(parameters)) return [];
 	const result = [];
-	for (const param of parameters) {
+	for (const [index, param] of parameters.entries()) {
 		if (!isObject(param)) continue;
-		const resolved = resolveParam(doc, param);
+		const entryPointer = `${pointerBase}/${String(index)}`;
+		const resolved = resolveParam(doc, param, diagnostics);
+		if (resolved === void 0) continue;
 		const name = getProperty(resolved, "name");
-		const location = getProperty(resolved, "in");
-		if (typeof name !== "string" || typeof location !== "string") continue;
+		const rawLocation = getProperty(resolved, "in");
+		if (typeof name !== "string" || typeof rawLocation !== "string") continue;
+		const location = toParameterLocation(rawLocation, name, `${entryPointer}/in`, diagnostics);
+		if (location === void 0) continue;
 		const schema = getProperty(resolved, "schema");
 		result.push({
 			name,
-			location: toParameterLocation(location),
+			location,
 			required: getProperty(resolved, "required") === true,
 			deprecated: getProperty(resolved, "deprecated") === true,
 			description: getString(resolved, "description"),
@@ -128,13 +187,64 @@ function extractParameterList(doc, parameters) {
 	}
 	return result;
 }
-function resolveParam(doc, param) {
-	const ref = getProperty(param, "$ref");
-	if (typeof ref === "string" && ref.startsWith("#/")) {
-		const resolved = resolveRefInDoc(doc, ref);
-		if (resolved !== void 0) return resolved;
-	}
-	return param;
+/**
+* Resolve a Reference Object chain on a non-Path-Item OpenAPI node
+* (Parameter, Header, Link, etc.). Single-hop resolution is insufficient
+* because OAS 3.x permits chains of Reference Objects of arbitrary
+* length — a Reference Object whose target is itself a Reference Object
+* is legal. `resolveRefChain` centralises cycle and depth-cap protection.
+*
+* Cycles and over-deep chains emit a dedicated diagnostic code per node
+* kind (`cyclic-parameter-ref`, `parameter-ref-too-deep`, and the
+* `header` / `link` equivalents), mirroring the existing
+* `swagger-cyclic-parameter-ref` precedent so consumers can pattern-match
+* directly on the code instead of filtering by `detail.kind`.
+*/
+function resolveReferenceObjectChain(doc, node, kind, diagnostics) {
+	const kindLabel = kind === "parameter" ? "Parameter Object" : kind === "header" ? "Header Object" : "Link Object";
+	const cyclicCode = kind === "parameter" ? "cyclic-parameter-ref" : kind === "header" ? "cyclic-header-ref" : "cyclic-link-ref";
+	const tooDeepCode = kind === "parameter" ? "parameter-ref-too-deep" : kind === "header" ? "header-ref-too-deep" : "link-ref-too-deep";
+	return resolveRefChain(node, {
+		lookup: (ref) => ref.startsWith("#/") ? resolveRefInDoc(doc, ref) : void 0,
+		onCycle: (ref) => {
+			emitDiagnostic(diagnostics, {
+				code: cyclicCode,
+				message: `Cyclic ${kindLabel} $ref "${ref}"`,
+				pointer: ref,
+				detail: {
+					ref,
+					kind
+				}
+			});
+		},
+		onDepthExceeded: (ref) => {
+			emitDiagnostic(diagnostics, {
+				code: tooDeepCode,
+				message: `${kindLabel} $ref chain exceeded the hop cap starting from "${ref}"`,
+				pointer: ref,
+				detail: {
+					ref,
+					kind
+				}
+			});
+		}
+	});
+}
+/**
+* Resolve a Parameter Object `$ref` chain. See
+* `resolveReferenceObjectChain` for the resolution contract.
+*/
+function resolveParam(doc, param, diagnostics) {
+	return resolveReferenceObjectChain(doc, param, "parameter", diagnostics);
+}
+/**
+* Encode a path segment for embedding in a JSON Pointer (RFC 6901).
+* `~` → `~0`, `/` → `~1`. Used to build pointer fragments for diagnostics
+* — the diagnostics layer does not currently re-encode segments inserted
+* via template strings.
+*/
+function jsonPointerEscape(segment) {
+	return segment.replace(/~/g, "~0").replace(/\//g, "~1");
 }
 function getRequestBody(parsed, path, method) {
 	const requestBodyRaw = getProperty(getProperty(lookupPathItem(parsed, path), method), "requestBody");
@@ -157,7 +267,7 @@ function getRequestBody(parsed, path, method) {
 		schema
 	};
 }
-function getResponses(parsed, path, method) {
+function getResponses(parsed, path, method, diagnostics) {
 	const responses = getProperty(getProperty(lookupPathItem(parsed, path), method), "responses");
 	if (!isObject(responses)) return [];
 	const result = [];
@@ -168,7 +278,7 @@ function getResponses(parsed, path, method) {
 		const content = getProperty(response, "content");
 		const contentTypes = isObject(content) ? Object.keys(content) : [];
 		const schema = isObject(content) ? extractSchemaFromContent(content) : void 0;
-		const headers = getResponseHeaders(response, parsed.doc);
+		const headers = getResponseHeaders(response, parsed.doc, diagnostics);
 		result.push({
 			statusCode,
 			description: getString(response, "description"),
@@ -186,15 +296,60 @@ function getResponses(parsed, path, method) {
 * 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).
+*
+* OpenAPI 3.1 Reference Object — sibling merge. OAS 3.1 explicitly
+* permits `summary` and `description` siblings of `$ref`; the wrapper's
+* siblings override the corresponding fields on the referenced node
+* (spec: "If the property is present on both the Reference Object and
+* the referenced node, the value on the Reference Object overrides the
+* value of the referenced node"). OAS 3.0 forbids siblings, so the merge
+* is gated on the document version. The gating is best-effort — if no
+* recognisable `openapi`/`swagger` field is present we err on the side
+* of NOT merging siblings to avoid changing behaviour for ambiguous or
+* partially-built documents.
 */
 function resolveWrapperRef(doc, wrapper) {
 	const ref = getString(wrapper, "$ref");
 	if (ref === void 0) return wrapper;
-	return resolveRefInDoc(doc, ref);
+	const target = resolveRefInDoc(doc, ref);
+	if (target === void 0) return void 0;
+	if (!documentAllowsReferenceSiblings(doc)) return target;
+	return mergeReferenceSiblings(wrapper, target);
+}
+/**
+* OAS 3.1 admits `summary` and `description` siblings on a Reference
+* Object; OAS 3.0 does not. Detect the document version once per call
+* — `detectOpenApiVersion` reads the top-level `openapi`/`swagger` field
+* and is cheap enough to call on every resolution without caching.
+*/
+function documentAllowsReferenceSiblings(doc) {
+	const version = detectOpenApiVersion(doc);
+	if (version === void 0) return false;
+	return version.major === 3 && version.minor >= 1;
+}
+/**
+* Per OAS 3.1, only `summary` and `description` siblings on a Reference
+* Object are permitted and they override the referenced node. Any other
+* sibling is ignored (spec: "Any properties of a Reference Object other
+* than those described above SHALL be ignored"). The returned object is
+* a fresh shallow merge — the input wrapper and target are not mutated.
+*/
+const REFERENCE_OBJECT_SIBLING_KEYS = ["summary", "description"];
+function mergeReferenceSiblings(wrapper, target) {
+	const merged = { ...target };
+	for (const key of REFERENCE_OBJECT_SIBLING_KEYS) {
+		const siblingValue = wrapper[key];
+		if (typeof siblingValue === "string") merged[key] = siblingValue;
+	}
+	return merged;
 }
 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 (mediaTypeBase(mediaType) !== "application/json") continue;
+		if (!isObject(mediaObj)) continue;
+		const schema = getProperty(mediaObj, "schema");
+		if (isObject(schema)) return schema;
+	}
 	for (const [mediaType, mediaObj] of Object.entries(content)) {
 		if (!isJsonSuffixMediaType(mediaType)) continue;
 		if (!isObject(mediaObj)) continue;
@@ -208,16 +363,24 @@ function extractSchemaFromContent(content) {
 	}
 }
 /**
+* Return the lowercased media-type base — the type/subtype with any
+* RFC 7231 parameters (`; charset=...`, `; profile=...`, etc.) stripped
+* and surrounding whitespace trimmed. Returns the empty string when the
+* input has no recognisable base (defensive against malformed entries).
+*/
+function mediaTypeBase(mediaType) {
+	return mediaType.toLowerCase().split(";", 1)[0]?.trim() ?? "";
+}
+/**
 * 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");
+	const base = mediaTypeBase(mediaType);
+	if (base === "application/json") return false;
+	return base.startsWith("application/") && base.endsWith("+json");
 }
 /**
 * Resolve an in-document `$ref` against the supplied doc root.
@@ -280,14 +443,13 @@ function getSecuritySchemes(parsed) {
 	}
 	return result;
 }
-function getResponseHeaders(response, doc) {
+function getResponseHeaders(response, doc, diagnostics) {
 	const result = /* @__PURE__ */ new Map();
 	const headers = getProperty(response, "headers");
 	if (!isObject(headers)) return result;
 	for (const [name, headerObj] of Object.entries(headers)) {
 		if (!isObject(headerObj)) continue;
-		const ref = getString(headerObj, "$ref");
-		const header = (ref !== void 0 && doc !== void 0 ? resolveRefInDoc(doc, ref) : void 0) ?? headerObj;
+		const header = doc !== void 0 ? resolveReferenceObjectChain(doc, headerObj, "header", diagnostics) ?? headerObj : headerObj;
 		const schemaProp = getProperty(header, "schema");
 		result.set(name, {
 			name,
@@ -299,20 +461,23 @@ function getResponseHeaders(response, doc) {
 	}
 	return result;
 }
-function listWebhooks(parsed) {
+function listWebhooks(parsed, diagnostics, seenIds = /* @__PURE__ */ new Map()) {
 	const result = [];
 	const webhooks = getProperty(parsed.doc, "webhooks");
 	if (!isObject(webhooks)) return result;
-	for (const [name, hookItem] of Object.entries(webhooks)) {
-		if (!isObject(hookItem)) continue;
+	for (const [name, rawHookItem] of Object.entries(webhooks)) {
+		const hookItem = resolvePathItem(parsed, rawHookItem, diagnostics);
+		if (hookItem === void 0) continue;
 		const operations = [];
-		for (const method of METHODS) {
+		for (const method of HTTP_METHODS) {
 			const operation = getProperty(hookItem, method);
 			if (!isObject(operation)) continue;
+			const operationId = getString(operation, "operationId");
+			recordOperationId(operationId, `${method.toUpperCase()} webhook:${name}`, `/webhooks/${jsonPointerEscape(name)}/${method}/operationId`, seenIds, diagnostics);
 			operations.push({
 				path: name,
 				method,
-				operationId: getString(operation, "operationId"),
+				operationId,
 				summary: getString(operation, "summary"),
 				description: getString(operation, "description"),
 				deprecated: getProperty(operation, "deprecated") === true,
@@ -326,6 +491,20 @@ function listWebhooks(parsed) {
 	}
 	return result;
 }
+/**
+* Enumerate every operation in the document — both the `paths` map and
+* the OpenAPI 3.1 `webhooks` map — sharing a single `seenIds` cache so
+* cross-list `operationId` collisions surface the same way as same-list
+* collisions. Returns the path-operation list followed by webhook
+* operations (flattened); callers that need the structured webhook
+* grouping should call `listWebhooks` directly.
+*/
+function listAllOperations(parsed, diagnostics) {
+	const seenIds = /* @__PURE__ */ new Map();
+	const pathOps = listOperations(parsed, diagnostics, seenIds);
+	const webhookOps = listWebhooks(parsed, diagnostics, seenIds).flatMap((w) => w.operations);
+	return [...pathOps, ...webhookOps];
+}
 function getExternalDocs(obj) {
 	const docs = getProperty(obj, "externalDocs");
 	if (!isObject(docs)) return void 0;
@@ -347,7 +526,7 @@ function getXmlInfo(schema) {
 		wrapped: getProperty(xml, "wrapped") === true
 	};
 }
-function listCallbacks(parsed, path, method) {
+function listCallbacks(parsed, path, method, diagnostics) {
 	const operation = getProperty(lookupPathItem(parsed, path), method);
 	if (!isObject(operation)) return [];
 	const callbacks = getProperty(operation, "callbacks");
@@ -356,21 +535,20 @@ function listCallbacks(parsed, path, method) {
 	for (const [name, callbackItem] of Object.entries(callbacks)) {
 		if (!isObject(callbackItem)) continue;
 		const operations = [];
-		for (const [cbPath, cbPathItem] of Object.entries(callbackItem)) {
-			if (!isObject(cbPathItem)) continue;
-			for (const cbMethod of METHODS) {
+		for (const [cbPath, rawCbPathItem] of Object.entries(callbackItem)) {
+			const cbPathItem = resolvePathItem(parsed, rawCbPathItem, diagnostics);
+			if (cbPathItem === void 0) continue;
+			for (const cbMethod of HTTP_METHODS) {
 				const cbOp = getProperty(cbPathItem, cbMethod);
 				if (!isObject(cbOp)) continue;
-				const ref = getString(cbOp, "$ref");
-				const resolved = ref !== void 0 ? resolveRefInDoc(parsed.doc, ref) ?? cbOp : cbOp;
 				operations.push({
 					path: `${name}/${cbPath}`,
 					method: cbMethod,
-					operationId: getString(resolved, "operationId"),
-					summary: getString(resolved, "summary"),
-					description: getString(resolved, "description"),
-					deprecated: getProperty(resolved, "deprecated") === true,
-					operation: isObject(resolved) ? resolved : cbOp
+					operationId: getString(cbOp, "operationId"),
+					summary: getString(cbOp, "summary"),
+					description: getString(cbOp, "description"),
+					deprecated: getProperty(cbOp, "deprecated") === true,
+					operation: cbOp
 				});
 			}
 		}
@@ -381,7 +559,7 @@ function listCallbacks(parsed, path, method) {
 	}
 	return result;
 }
-function getLinks(parsed, path, method, statusCode) {
+function getLinks(parsed, path, method, statusCode, diagnostics) {
 	const response = getProperty(getProperty(getProperty(lookupPathItem(parsed, path), method), "responses"), statusCode);
 	if (!isObject(response)) return [];
 	const links = getProperty(response, "links");
@@ -389,9 +567,7 @@ function getLinks(parsed, path, method, statusCode) {
 	const result = [];
 	for (const [name, linkObj] of Object.entries(links)) {
 		if (!isObject(linkObj)) continue;
-		const ref = getString(linkObj, "$ref");
-		const resolved = ref !== void 0 ? resolveRefInDoc(parsed.doc, ref) ?? linkObj : linkObj;
-		const link = isObject(resolved) ? resolved : linkObj;
+		const link = resolveReferenceObjectChain(parsed.doc, linkObj, "link", diagnostics) ?? linkObj;
 		const params = getProperty(link, "parameters");
 		const paramMap = /* @__PURE__ */ new Map();
 		if (isObject(params)) {
@@ -409,4 +585,4 @@ function getLinks(parsed, path, method, statusCode) {
 	return result;
 }
 //#endregion
-export { getExternalDocs, getLinks, getParameters, getRequestBody, getResponseHeaders, getResponses, getSchema, getSecurityRequirements, getSecuritySchemes, getXmlInfo, listCallbacks, listOperations, listWebhooks, parseOpenApiDocument };
+export { getExternalDocs, getLinks, getParameters, getRequestBody, getResponseHeaders, getResponses, getSchema, getSecurityRequirements, getSecuritySchemes, getXmlInfo, listAllOperations, listCallbacks, listOperations, listWebhooks, parseOpenApiDocument };

package/dist/openapi/resolve.d.mts

@@ -1,4 +1,4 @@
-import { i as DiagnosticsOptions } from "../diagnostics-D0QCYGv0.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-Cbwak-ZX.mjs";
 import { OpenApiDocument, OperationInfo, ParameterInfo, ResponseInfo, getRequestBody } from "./parser.mjs";
 
 //#region src/openapi/resolve.d.ts
@@ -15,17 +15,26 @@ import { OpenApiDocument, OperationInfo, ParameterInfo, ResponseInfo, getRequest
  * same form `<SchemaComponent>` does, keeping the OpenAPI components on
  * the same pipeline as the top-level adapter.
  *
- * 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.
+ * ### Caching and diagnostics
  *
- * The cache is keyed by the caller-supplied document so subsequent
- * cache-eligible calls with the same input bypass both normalisation
- * and parsing.
+ * Normalisation runs at most once per document identity. The full set
+ * of doc-level diagnostics emitted during that single run is captured
+ * into the cache alongside the parsed result. Each caller-supplied
+ * sink receives the captured diagnostics exactly once per cached
+ * entry, no matter how many times `getParsed` is called with that
+ * `(doc, sink)` pair.
+ *
+ * The previous implementation bypassed the cache whenever
+ * `diagnostics` was supplied and re-ran the entire normalisation
+ * pipeline against the new sink. That fired every doc-level
+ * diagnostic once per call, so a parent like `ApiWebhooks` that
+ * renders `ApiWebhook` per webhook entry caused N-fold emission of a
+ * single real cause. With the new strategy, cardinality stays at one
+ * per real cause regardless of how many child renders share the
+ * sink.
+ *
+ * Strict mode is treated as a per-call invariant — see
+ * {@link replayCapturedDiagnostics} for the rationale.
  */
 declare function getParsed(doc: Record<string, unknown>, diagnostics?: DiagnosticsOptions): OpenApiDocument;
 /**