schema-components 1.21.0 → 1.23.0

package/dist/openapi/parser.mjs

@@ -1,13 +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();
@@ -29,46 +53,79 @@ 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.
+*
+* 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 ref = getString(pathItem, "$ref");
-	if (ref === void 0) return pathItem;
-	return resolveRefInDoc(parsed.doc, ref) ?? void 0;
+	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) {
+function listOperations(parsed, diagnostics) {
 	const operations = [];
 	const paths = getProperty(parsed.doc, "paths");
 	if (!isObject(paths)) return operations;
+	const seenIds = /* @__PURE__ */ new Map();
 	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");
+			if (operationId !== void 0) {
+				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 ${method.toUpperCase()} ${path})`,
+					pointer: `/paths/${jsonPointerEscape(path)}/${method}/operationId`,
+					detail: {
+						operationId,
+						firstSeenAt,
+						duplicateAt: `${method.toUpperCase()} ${path}`
+					}
+				});
+				else seenIds.set(operationId, `${method.toUpperCase()} ${path}`);
+			}
 			operations.push({
 				path,
 				method,
-				operationId: getString(operation, "operationId"),
+				operationId,
 				summary: getString(operation, "summary"),
 				description: getString(operation, "description"),
 				deprecated: getProperty(operation, "deprecated") === true,
@@ -78,31 +135,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"),
@@ -111,13 +172,69 @@ 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 reuse the existing `cyclic-path-item-ref`
+* and `path-item-ref-too-deep` diagnostic codes with a
+* `detail.kind: "<node-kind>"` discriminator (e.g. `"parameter"`,
+* `"header"`, `"link"`). There is no dedicated code per node kind in the
+* current `DiagnosticCode` union; consumers filter by `detail.kind` when
+* they care to distinguish the source.
+*
+* TODO(round7-integration): consider adding dedicated `cyclic-*-ref` /
+* `*-ref-too-deep` codes per node kind to `core/diagnostics.ts` so the
+* kind discriminator on `detail` is not needed. The existing Swagger
+* 2.0 path already uses a dedicated `swagger-cyclic-parameter-ref` for
+* the equivalent failure mode.
+*/
+function resolveReferenceObjectChain(doc, node, kind, diagnostics) {
+	const kindLabel = kind === "parameter" ? "Parameter Object" : kind === "header" ? "Header Object" : "Link Object";
+	return resolveRefChain(node, {
+		lookup: (ref) => ref.startsWith("#/") ? resolveRefInDoc(doc, ref) : void 0,
+		onCycle: (ref) => {
+			emitDiagnostic(diagnostics, {
+				code: "cyclic-path-item-ref",
+				message: `Cyclic ${kindLabel} $ref "${ref}"`,
+				pointer: ref,
+				detail: {
+					ref,
+					kind
+				}
+			});
+		},
+		onDepthExceeded: (ref) => {
+			emitDiagnostic(diagnostics, {
+				code: "path-item-ref-too-deep",
+				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");
@@ -140,7 +257,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 = [];
@@ -151,7 +268,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"),
@@ -169,15 +286,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;
@@ -191,17 +353,40 @@ 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.
+*
+* 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("/");
@@ -248,14 +433,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,
@@ -267,14 +451,15 @@ function getResponseHeaders(response, doc) {
 	}
 	return result;
 }
-function listWebhooks(parsed) {
+function listWebhooks(parsed, diagnostics) {
 	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;
 			operations.push({
@@ -315,7 +500,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");
@@ -324,21 +509,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
 				});
 			}
 		}
@@ -349,7 +533,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");
@@ -357,9 +541,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)) {

package/dist/openapi/resolve.d.mts

@@ -1,4 +1,4 @@
-import { i as DiagnosticsOptions } from "../diagnostics-CbBPsxSt.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-BS2kaUyE.mjs";
 import { OpenApiDocument, OperationInfo, ParameterInfo, ResponseInfo, getRequestBody } from "./parser.mjs";
 
 //#region src/openapi/resolve.d.ts
@@ -15,24 +15,40 @@ 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;
 /**
- * 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.
@@ -59,7 +75,7 @@ interface ResolvedOperation {
  * normalisation pipeline (every re-run would emit each diagnostic
  * again into the sink).
  */
-declare function resolveOperationFromParsed(parsed: OpenApiDocument, path: string, method: string): ResolvedOperation;
+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.