@kubb/ast 5.17.1 → 5.18.1

package/dist/index.d.ts

@@ -293,6 +293,16 @@ type SchemaNodeBase = BaseNode & {
    * Schema `format` value.
    */
   format?: string;
+  externalDocs?: ExternalDocs;
+  /**
+   * `if`/`then`/`else`, `dependentRequired` and `dependentSchemas`. A required `unknown` property in `if` means "key is present".
+   * Visitors do not walk it.
+   */
+  conditionals?: Array<{
+    if: SchemaNode;
+    then?: SchemaNode;
+    else?: SchemaNode;
+  }>;
 };
 /**
  * Object schema with ordered properties.
@@ -349,10 +359,18 @@ type ObjectSchemaNode = SchemaNodeBase & {
   /**
    * Minimum number of properties allowed.
    */
-  minProperties?: number;
+  min?: number;
   /**
    * Maximum number of properties allowed.
    */
+  max?: number;
+  /**
+   * @deprecated Use `min`. Removed in Kubb v6.
+   */
+  minProperties?: number;
+  /**
+   * @deprecated Use `max`. Removed in Kubb v6.
+   */
   maxProperties?: number;
 };
 /**
@@ -392,6 +410,14 @@ type ArraySchemaNode = SchemaNodeBase & {
    * Whether all items must be unique.
    */
   unique?: boolean;
+  /**
+   * At least `min` (default 1) and at most `max` items match `schema`. Visitors do not walk `schema`.
+   */
+  contains?: {
+    schema: SchemaNode;
+    min?: number;
+    max?: number;
+  };
 };
 /**
  * Shared shape for union and intersection schemas.
@@ -627,6 +653,14 @@ type StringSchemaNode = SchemaNodeBase & {
    * Regex pattern.
    */
   pattern?: string;
+  /**
+   * The value the string encodes, such as a JSON document or `base64` bytes. Visitors do not walk `schema`.
+   */
+  content?: {
+    mediaType?: string;
+    encoding?: string;
+    schema?: SchemaNode;
+  };
 };
 /**
  * Numeric schema (`number`, `integer`, or `bigint`).
@@ -650,11 +684,18 @@ type NumberSchemaNode = SchemaNodeBase & {
    */
   max?: number;
   /**
-   * Exclusive minimum value.
+   * Bounds the value may not equal: it must be greater than `min` and less than `max`.
+   */
+  exclusive?: {
+    min?: number;
+    max?: number;
+  };
+  /**
+   * @deprecated Use `exclusive.min`. Removed in Kubb v6.
    */
   exclusiveMinimum?: number;
   /**
-   * Exclusive maximum value.
+   * @deprecated Use `exclusive.max`. Removed in Kubb v6.
    */
   exclusiveMaximum?: number;
   /**
@@ -801,6 +842,7 @@ type InputServerVariable = {
  */
 type InputServer = {
   url: string;
+  name?: string;
   description?: string;
   /**
    * Variables of the source URL template, copied as-is. `url` already has their defaults filled in, so
@@ -808,18 +850,66 @@ type InputServer = {
    */
   variables?: Record<string, InputServerVariable>;
 };
+type ExternalDocs = {
+  url: string;
+  description?: string;
+};
+type InputTag = {
+  name: string;
+  summary?: string;
+  description?: string;
+  /**
+   * Name of the tag this tag nests under. `group: { type: 'tag' }` places its files in the parent's folder.
+   */
+  parent?: string;
+  kind?: string;
+  externalDocs?: ExternalDocs;
+};
+type OAuthFlow = {
+  authorizationUrl?: string;
+  deviceAuthorizationUrl?: string;
+  tokenUrl?: string;
+  refreshUrl?: string;
+  scopes?: Record<string, string>;
+};
+/**
+ * How a client sends a credential, in the same shape as the `Auth` object the generated clients pass to `auth`.
+ */
+type AuthCredential = {
+  type: 'http';
+  scheme: 'bearer' | 'basic' | (string & {});
+  bearerFormat?: string;
+} | {
+  type: 'apiKey';
+  in: 'header' | 'query' | 'cookie';
+  name: string;
+} | {
+  type: 'oauth2';
+  flows: Record<string, OAuthFlow>;
+  metadataUrl?: string;
+} | {
+  type: 'openIdConnect';
+  url?: string;
+} | {
+  type: 'mutualTLS';
+};
 /**
- * An authentication scheme from the source document, keyed by `name`. `parameterName` is the header, query, or cookie name of an `apiKey`.
+ * One way to authenticate, keyed by `name`, which operations refer to in `auth`.
  */
-type InputSecurityScheme = {
+type AuthScheme = {
   name: string;
-  type: string;
   description?: string;
-  scheme?: string;
-  bearerFormat?: string;
-  in?: string;
-  parameterName?: string;
+  deprecated?: boolean;
+  credential: AuthCredential;
 };
+/**
+ * One way to meet an operation's auth. Every scheme in it applies together. `scopes` are the OAuth2 or OpenID
+ * Connect scopes the call needs. An empty list means the call may be sent without credentials.
+ */
+type AuthRequirement = Array<{
+  scheme: string;
+  scopes?: Array<string>;
+}>;
 /**
  * Metadata for an API document, populated by the adapter and available to every generator.
  * Every field is a plain JSON value.
@@ -842,12 +932,26 @@ type InputMeta = {
    * API version string from `info.version` in the source document.
    */
   version?: string;
+  summary?: string;
+  termsOfService?: string;
+  contact?: {
+    name?: string;
+    url?: string;
+    email?: string;
+  };
+  license?: {
+    name: string;
+    identifier?: string;
+    url?: string;
+  };
+  externalDocs?: ExternalDocs;
   /**
    * Resolved base URL from the first matching server entry in the source document.
    */
   baseURL?: string | null;
   servers?: Array<InputServer>;
-  securitySchemes?: Array<InputSecurityScheme>;
+  tags?: Array<InputTag>;
+  auth?: Array<AuthScheme>;
   /**
    * Vendor extensions (`x-*` keys) from the document root, copied as-is. Absent when the root has none.
    */
@@ -896,83 +1000,6 @@ type InputNode = BaseNode & {
  * ```
  */
 declare function createInput(overrides?: Partial<Omit<InputNode, 'kind'>>): InputNode;
-/**
- * Where a parameter is sent. `querystring` carries the whole query string as one value, serialized per `contentType`.
- */
-type ParameterLocation = 'path' | 'query' | 'header' | 'cookie' | 'querystring';
-/**
- * Parameter serialization style, controlling how a parameter value is rendered into the request.
- */
-type ParameterStyle = 'matrix' | 'label' | 'form' | 'simple' | 'spaceDelimited' | 'pipeDelimited' | 'deepObject';
-/**
- * AST node representing one operation parameter.
- *
- * @example
- * ```ts
- * const param: ParameterNode = {
- *   kind: 'Parameter',
- *   name: 'petId',
- *   in: 'path',
- *   schema: createSchema({ type: 'string' }),
- *   required: true,
- * }
- * ```
- */
-type ParameterNode = BaseNode & {
-  kind: 'Parameter';
-  /**
-   * Parameter name.
-   */
-  name: string;
-  /**
-   * Parameter location (`path`, `query`, `header`, `cookie`, or `querystring`).
-   */
-  in: ParameterLocation;
-  /**
-   * Parameter schema.
-   */
-  schema: SchemaNode;
-  /**
-   * Whether the parameter is required.
-   */
-  required: boolean;
-  /**
-   * Serialization style. Absent when the source omits it, leaving consumers to apply the
-   * per-location default.
-   */
-  style?: ParameterStyle;
-  /**
-   * Whether array and object values expand into separate values. Absent when the source omits it,
-   * leaving consumers to apply the default for the style.
-   */
-  explode?: boolean;
-  /**
-   * Whether reserved characters (RFC 3986 `:/?#[]@!$&'()*+,;=`) are sent as-is instead of
-   * percent-encoded. Only applies to query parameters. Absent when the source omits it.
-   */
-  allowReserved?: boolean;
-  /**
-   * Media type of a parameter described with `content` instead of `schema`, for example
-   * `application/json` when the value is sent as a JSON-encoded string. Absent for `schema` parameters.
-   */
-  contentType?: string;
-};
-type UserParameterNode = Pick<ParameterNode, 'name' | 'in' | 'schema'> & Partial<Omit<ParameterNode, 'kind' | 'name' | 'in' | 'schema'>>;
-/**
- * Creates a `ParameterNode`. `required` defaults to `false`, and the schema's
- * `optional`/`nullish` flags are derived from it.
- *
- * @example
- * ```ts
- * const param = createParameter({
- *   name: 'petId',
- *   in: 'path',
- *   required: true,
- *   schema: createSchema({ type: 'string' }),
- * })
- * ```
- */
-declare function createParameter(input: UserParameterNode): ParameterNode;
 /**
  * How one body property is serialized, from the `encoding` entry of its media type.
  */
@@ -993,6 +1020,16 @@ type EncodingNode = {
    * Whether reserved characters are sent as-is instead of percent-encoded.
    */
   allowReserved?: boolean;
+  encoding?: Record<string, EncodingNode>;
+  prefixEncoding?: Array<EncodingNode>;
+  itemEncoding?: EncodingNode;
+};
+type ExampleNode = {
+  name?: string;
+  summary?: string;
+  description?: string;
+  value?: unknown;
+  serializedValue?: string;
 };
 /**
  * AST node representing one content-type entry of a request body or response.
@@ -1046,11 +1083,100 @@ type ContentNode = BaseNode & {
    * Serialization settings per body property that sets at least one field in the spec's `encoding`.
    */
   encoding?: Record<string, EncodingNode>;
+  examples?: Array<ExampleNode>;
+  /**
+   * Serialization of the first parts by position, for a body sent as an array of parts such as `multipart/mixed`.
+   */
+  prefixEncoding?: Array<EncodingNode>;
+  /**
+   * Serialization of every part after `prefixEncoding`, for a body sent as an array of parts such as `multipart/mixed`.
+   */
+  itemEncoding?: EncodingNode;
 };
 /**
  * Creates a `ContentNode` for a single request-body or response content type.
  */
 declare const createContent: (input: Omit<ContentNode, "kind">) => ContentNode;
+/**
+ * Where a parameter is sent. `querystring` carries the whole query string as one value, serialized per `contentType`.
+ */
+type ParameterLocation = 'path' | 'query' | 'header' | 'cookie' | 'querystring';
+/**
+ * Parameter serialization style, controlling how a parameter value is rendered into the request.
+ */
+type ParameterStyle = 'matrix' | 'label' | 'form' | 'simple' | 'spaceDelimited' | 'pipeDelimited' | 'deepObject' | 'cookie';
+/**
+ * AST node representing one operation parameter.
+ *
+ * @example
+ * ```ts
+ * const param: ParameterNode = {
+ *   kind: 'Parameter',
+ *   name: 'petId',
+ *   in: 'path',
+ *   schema: createSchema({ type: 'string' }),
+ *   required: true,
+ * }
+ * ```
+ */
+type ParameterNode = BaseNode & {
+  kind: 'Parameter';
+  /**
+   * Parameter name.
+   */
+  name: string;
+  /**
+   * Parameter location (`path`, `query`, `header`, `cookie`, or `querystring`).
+   */
+  in: ParameterLocation;
+  /**
+   * Parameter schema.
+   */
+  schema: SchemaNode;
+  /**
+   * Whether the parameter is required.
+   */
+  required: boolean;
+  /**
+   * Serialization style. Absent when the source omits it, leaving consumers to apply the
+   * per-location default.
+   */
+  style?: ParameterStyle;
+  /**
+   * Whether array and object values expand into separate values. Absent when the source omits it,
+   * leaving consumers to apply the default for the style.
+   */
+  explode?: boolean;
+  /**
+   * Whether reserved characters (RFC 3986 `:/?#[]@!$&'()*+,;=`) are sent as-is instead of
+   * percent-encoded. Absent when the source omits it.
+   */
+  allowReserved?: boolean;
+  /**
+   * Media type of a parameter described with `content` instead of `schema`, for example
+   * `application/json` when the value is sent as a JSON-encoded string. Absent for `schema` parameters.
+   */
+  contentType?: string;
+  examples?: Array<ExampleNode>;
+  deprecated?: boolean;
+  allowEmptyValue?: boolean;
+};
+type UserParameterNode = Pick<ParameterNode, 'name' | 'in' | 'schema'> & Partial<Omit<ParameterNode, 'kind' | 'name' | 'in' | 'schema'>>;
+/**
+ * Creates a `ParameterNode`. `required` defaults to `false`, and the schema's
+ * `optional`/`nullish` flags are derived from it.
+ *
+ * @example
+ * ```ts
+ * const param = createParameter({
+ *   name: 'petId',
+ *   in: 'path',
+ *   required: true,
+ *   schema: createSchema({ type: 'string' }),
+ * })
+ * ```
+ */
+declare function createParameter(input: UserParameterNode): ParameterNode;
 /**
  * AST node representing an operation request body.
  *
@@ -1095,7 +1221,7 @@ type Digit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
 /**
  * Response status code literal used by operations.
  *
- * Includes three-digit HTTP status code strings and `"default"` for catch-all responses.
+ * Includes three-digit HTTP status code strings, ranges such as `"2xx"`, and `"default"` for catch-all responses.
  *
  * @example
  * ```ts
@@ -1103,7 +1229,7 @@ type Digit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
  * const fallback: StatusCode = 'default'
  * ```
  */
-type StatusCode = `${1 | 2 | 3 | 4 | 5}${Digit}${Digit}` | 'default';
+type StatusCode = `${1 | 2 | 3 | 4 | 5}${Digit}${Digit}` | `${1 | 2 | 3 | 4 | 5}xx` | 'default';
 /**
  * AST node representing one operation response variant.
  *
@@ -1129,6 +1255,7 @@ type ResponseNode = BaseNode & {
    * HTTP status code or `'default'` for a fallback response.
    */
   statusCode: StatusCode;
+  summary?: string;
   /**
    * Optional response description.
    */
@@ -1150,6 +1277,22 @@ type ResponseNode = BaseNode & {
    * ```
    */
   content?: Array<ContentNode>;
+  /**
+   * Response headers, as `in: 'header'` parameters. `Content-Type` is left out.
+   */
+  headers?: Array<ParameterNode>;
+  links?: Record<string, ResponseLink>;
+};
+/**
+ * A link to another operation. `parameters` and `requestBody` hold runtime expressions such as `$response.body#/id`.
+ */
+type ResponseLink = {
+  operationId?: string;
+  operationRef?: string;
+  parameters?: Record<string, unknown>;
+  requestBody?: unknown;
+  description?: string;
+  server?: InputServer;
 };
 type ResponseInput = Pick<ResponseNode, 'statusCode'> & Partial<Omit<ResponseNode, 'kind' | 'statusCode' | 'content'>> & {
   content?: Array<ContentNode>;
@@ -1204,6 +1347,7 @@ type OperationNodeBase = BaseNode & {
    * Marks the operation as deprecated.
    */
   deprecated?: boolean;
+  externalDocs?: ExternalDocs;
   /**
    * Query, path, header, and cookie parameters for the operation.
    */
@@ -1222,6 +1366,10 @@ type OperationNodeBase = BaseNode & {
   extensions?: Record<string, unknown>;
   /** The operation's own `servers`, else its path item's, such as an upload host. Absent when neither declares any. */
   servers?: Array<InputServer>;
+  /**
+   * Ways to authenticate, from the operation or else the document. Any one entry is enough. `[]` means no auth.
+   */
+  auth?: Array<AuthRequirement>;
 };
 /**
  * Operation served over HTTP. `method` and `path` are guaranteed.
@@ -2515,7 +2663,8 @@ export declare function collectSchemaRefs(node: SchemaNode): ReadonlySet<string>
  *
  * Only refs that carry a `$ref` pointer count, so a synthesized ref pointing at a sibling in the
  * same file (a union member created by name) is left out. That leaves exactly the set
- * `resolver.imports` emits.
+ * `resolver.imports` emits. Refs inside `conditionals`, `contains` and `content` count only with
+ * `checks: true`, for a plugin that prints those checks.
  *
  * @example
  * ```ts
@@ -2523,7 +2672,9 @@ export declare function collectSchemaRefs(node: SchemaNode): ReadonlySet<string>
  * // ['Category', 'Tag']
  * ```
  */
-export declare function collectImportedRefNames(node: SchemaNode): ReadonlyArray<string>;
+export declare function collectImportedRefNames(node: SchemaNode, { checks }?: {
+  checks?: boolean;
+}): ReadonlyArray<string>;
 /**
  * Collects the names of all top-level schemas transitively used by a set of operations.
  *
@@ -2673,7 +2824,7 @@ type ParserOptions = {
   enumSuffix: 'enum' | (string & {});
 };
 declare namespace index_d_exports {
-  export { ArraySchemaNode, ArrowFunctionNode, BreakNode, CodeNode, ConstNode, ContentNode, DateOnlyTypeValue, DateSchemaNode, DateTimeTypeValue, DateTypeOptions, DatetimeSchemaNode, DistributiveOmit, EncodingNode, Enforce, EnumSchemaNode, ExportNode, FileNode, FunctionNode, GenericOperationNode, HttpMethod, HttpOperationNode, ImportNode, InlineLanguage, InputMeta, InputNode, InputSecurityScheme, InputServer, IntersectionSchemaNode, JSDocNode, JsxNode, Macro, Node, NodeKind, NotSchemaNode, NumberSchemaNode, ObjectSchemaNode, OperationNode, ParameterLocation, ParameterNode, ParameterStyle, ParserOptions, PrimitiveSchemaType, Printer, PrinterFactoryOptions, PrinterPartial, PropertyNode, RefSchemaNode, RequestBodyNode, ResponseNode, ScalarSchemaNode, ScalarSchemaType, SchemaNode, SchemaNodeByType, SchemaType, SourceNode, StatusCode, StringSchemaNode, TextNode, TimeSchemaNode, TypeNode, UnionSchemaNode, UrlSchemaNode, UserFileNode, Visitor, VisitorContext, applyMacros, index_d_exports as ast, collect, collectImportedRefNames, collectSchemaRefs, collectSync, collectUsedSchemaNames, compareEnforce, createPrinter, defineMacro, extractStringsFromNodes, index_d_exports$1 as factory, findCircularSchemas, findSchema, getSchemaLiteralValues, inferDiscriminatorPropertyName, inlineFiles, isBareRef, isHttpOperationNode, mergeRefWithSchema, narrowSchema, nodeKinds, optionality, refName, resolveRef, resolveRefName, resolveSchemaProperties, schemaTypes, transform };
+  export { ArraySchemaNode, ArrowFunctionNode, AuthCredential, AuthRequirement, AuthScheme, BreakNode, CodeNode, ConstNode, ContentNode, DateOnlyTypeValue, DateSchemaNode, DateTimeTypeValue, DateTypeOptions, DatetimeSchemaNode, DistributiveOmit, EncodingNode, Enforce, EnumSchemaNode, ExampleNode, ExportNode, ExternalDocs, FileNode, FunctionNode, GenericOperationNode, HttpMethod, HttpOperationNode, ImportNode, InlineLanguage, InputMeta, InputNode, InputServer, InputTag, IntersectionSchemaNode, JSDocNode, JsxNode, Macro, Node, NodeKind, NotSchemaNode, NumberSchemaNode, OAuthFlow, ObjectSchemaNode, OperationNode, ParameterLocation, ParameterNode, ParameterStyle, ParserOptions, PrimitiveSchemaType, Printer, PrinterFactoryOptions, PrinterPartial, PropertyNode, RefSchemaNode, RequestBodyNode, ResponseLink, ResponseNode, ScalarSchemaNode, ScalarSchemaType, SchemaNode, SchemaNodeByType, SchemaType, SourceNode, StatusCode, StringSchemaNode, TextNode, TimeSchemaNode, TypeNode, UnionSchemaNode, UrlSchemaNode, UserFileNode, Visitor, VisitorContext, applyMacros, index_d_exports as ast, collect, collectImportedRefNames, collectSchemaRefs, collectSync, collectUsedSchemaNames, compareEnforce, createPrinter, defineMacro, extractStringsFromNodes, index_d_exports$1 as factory, findCircularSchemas, findSchema, getSchemaLiteralValues, inferDiscriminatorPropertyName, inlineFiles, isBareRef, isHttpOperationNode, mergeRefWithSchema, narrowSchema, nodeKinds, optionality, refName, resolveRef, resolveRefName, resolveSchemaProperties, schemaTypes, transform };
 }
-export { type ArraySchemaNode, type ArrowFunctionNode, type BreakNode, type CodeNode, type ConstNode, type ContentNode, type DateOnlyTypeValue, type DateSchemaNode, type DateTimeTypeValue, type DateTypeOptions, type DatetimeSchemaNode, type DistributiveOmit, type EncodingNode, type Enforce, type EnumSchemaNode, type ExportNode, type FileNode, type FunctionNode, type GenericOperationNode, type HttpMethod, type HttpOperationNode, type ImportNode, type InlineLanguage, type InputMeta, type InputNode, type InputSecurityScheme, type InputServer, type IntersectionSchemaNode, type JSDocNode, type JsxNode, type Macro, type Node, type NodeKind, type NotSchemaNode, type NumberSchemaNode, type ObjectSchemaNode, type OperationNode, type ParameterLocation, type ParameterNode, type ParameterStyle, type ParserOptions, type PrimitiveSchemaType, type Printer, type PrinterFactoryOptions, type PrinterPartial, type PropertyNode, type RefSchemaNode, type RequestBodyNode, type ResponseNode, type ScalarSchemaNode, type ScalarSchemaType, type SchemaNode, type SchemaNodeByType, type SchemaType, type SourceNode, type StatusCode, type StringSchemaNode, type TextNode, type TimeSchemaNode, type TypeNode, type UnionSchemaNode, type UrlSchemaNode, type UserFileNode, type Visitor, type VisitorContext, index_d_exports as ast, index_d_exports$1 as factory };
+export { type ArraySchemaNode, type ArrowFunctionNode, type AuthCredential, type AuthRequirement, type AuthScheme, type BreakNode, type CodeNode, type ConstNode, type ContentNode, type DateOnlyTypeValue, type DateSchemaNode, type DateTimeTypeValue, type DateTypeOptions, type DatetimeSchemaNode, type DistributiveOmit, type EncodingNode, type Enforce, type EnumSchemaNode, type ExampleNode, type ExportNode, type ExternalDocs, type FileNode, type FunctionNode, type GenericOperationNode, type HttpMethod, type HttpOperationNode, type ImportNode, type InlineLanguage, type InputMeta, type InputNode, type InputServer, type InputTag, type IntersectionSchemaNode, type JSDocNode, type JsxNode, type Macro, type Node, type NodeKind, type NotSchemaNode, type NumberSchemaNode, type OAuthFlow, type ObjectSchemaNode, type OperationNode, type ParameterLocation, type ParameterNode, type ParameterStyle, type ParserOptions, type PrimitiveSchemaType, type Printer, type PrinterFactoryOptions, type PrinterPartial, type PropertyNode, type RefSchemaNode, type RequestBodyNode, type ResponseLink, type ResponseNode, type ScalarSchemaNode, type ScalarSchemaType, type SchemaNode, type SchemaNodeByType, type SchemaType, type SourceNode, type StatusCode, type StringSchemaNode, type TextNode, type TimeSchemaNode, type TypeNode, type UnionSchemaNode, type UrlSchemaNode, type UserFileNode, type Visitor, type VisitorContext, index_d_exports as ast, index_d_exports$1 as factory };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -188,7 +188,7 @@ const VISITOR_KEYS = {
 	],
 	RequestBody: ["content"],
 	Content: ["schema", "stream"],
-	Response: ["content"],
+	Response: ["content", "headers"],
 	Schema: [
 		"properties",
 		"items",
@@ -201,6 +201,15 @@ const VISITOR_KEYS = {
 	Property: ["schema"],
 	Parameter: ["schema"]
 };
+/**
+* Schema fields that hold checks rather than shape: the `conditionals` entries, `contains` and a string's `content`.
+* `transform` and `collect` skip them, and `visitChildNodes` walks them with `checks: true`.
+*/
+const schemaCheckKeys = [
+	"conditionals",
+	"contains",
+	"content"
+];
 /** Visitor callback names in traversal order, the keys of {@link Visitor}. */
 const visitorKeys = [
 	"input",
@@ -251,28 +260,35 @@ function getChildren(node, recurse) {
 	});
 	return children;
 }
-/** Calls `visit` for each direct child node and stops at the first call that returns `true`. */
-function visitChildNodes(node, visit) {
-	const keys = VISITOR_KEYS[node.kind];
+/**
+* Calls `visit` for each direct child node and stops at the first call that returns `true`.
+* With `checks: true`, a schema's {@link schemaCheckKeys} fields are walked too.
+*/
+function visitChildNodes(node, visit, { checks = false } = {}) {
+	const keys = checks && node.kind === nodeKinds.schema ? [...VISITOR_KEYS[node.kind] ?? [], ...schemaCheckKeys] : VISITOR_KEYS[node.kind];
 	if (!keys) return false;
 	const record = node;
 	const seen = /* @__PURE__ */ new Set();
 	const visitOnce = (child) => !seen.has(child) && (seen.add(child), visit(child));
+	const visitRecord = (value) => {
+		for (const name in value) {
+			if (!Object.hasOwn(value, name)) continue;
+			const item = value[name];
+			if (isNode(item) && visitOnce(item)) return true;
+		}
+		return false;
+	};
 	for (const key of keys) {
 		const value = record[key];
 		if (Array.isArray(value)) {
-			for (const item of value) if (isNode(item) && visitOnce(item)) return true;
+			for (const item of value) if (isNode(item) ? visitOnce(item) : isNodeRecord(item) && visitRecord(item)) return true;
 			continue;
 		}
 		if (isNode(value)) {
 			if (visitOnce(value)) return true;
 			continue;
 		}
-		if (isNodeRecord(value)) for (const name in value) {
-			if (!Object.hasOwn(value, name)) continue;
-			const item = value[name];
-			if (isNode(item) && visitOnce(item)) return true;
-		}
+		if (isNodeRecord(value) && visitRecord(value)) return true;
 	}
 	return false;
 }
@@ -1181,23 +1197,33 @@ function memo(store, key, compute) {
 	return value;
 }
 // src/utils/schemaGraph.ts
-/**
-* Walks a node's subtree once and lists every ref it holds, in traversal order, as the resolved
-* name plus whether the ref carries a `$ref` pointer. Memoized by node identity, so
-* `collectSchemaRefs` and `collectImportedRefNames` share one scan per schema.
-*/
 const refEntries = /* @__PURE__ */ new WeakMap();
+const checkRefEntries = /* @__PURE__ */ new WeakMap();
 const schemaRefs = /* @__PURE__ */ new WeakMap();
 const importedRefNames = /* @__PURE__ */ new WeakMap();
-function collectRefEntries(node) {
-	return memo(refEntries, node, () => collectSync(node, { schema(child) {
-		if (child.type !== "ref") return void 0;
-		const name = resolveRefName(child);
-		return name ? {
-			name,
-			hasPointer: Boolean(child.ref)
-		} : void 0;
-	} }));
+const importedCheckRefNames = /* @__PURE__ */ new WeakMap();
+/**
+* Walks a node's subtree once and lists every ref it holds, in traversal order, as the resolved
+* name plus whether the ref carries a `$ref` pointer. Memoized per node and per `checks` mode, so
+* each helper below scans a schema once.
+*/
+function collectRefEntries(node, { checks }) {
+	return memo(checks ? checkRefEntries : refEntries, node, () => {
+		const entries = [];
+		const walk = (current) => {
+			if (current.kind === nodeKinds.schema && current.type === "ref") {
+				const name = resolveRefName(current);
+				if (name) entries.push({
+					name,
+					hasPointer: Boolean(current.ref)
+				});
+			}
+			visitChildNodes(current, walk, { checks });
+			return false;
+		};
+		walk(node);
+		return entries;
+	});
 }
 /**
 * Collects the names of every schema a node's subtree references, resolved with `resolveRefName`.
@@ -1211,7 +1237,7 @@ function collectRefEntries(node) {
 * ```
 */
 function collectSchemaRefs(node) {
-	return memo(schemaRefs, node, () => new Set(collectRefEntries(node).map((entry) => entry.name)));
+	return memo(schemaRefs, node, () => new Set(collectRefEntries(node, { checks: true }).map((entry) => entry.name)));
 }
 /**
 * Collects the de-duplicated target names of every pointer-carrying ref in a node's subtree, in
@@ -1220,7 +1246,8 @@ function collectSchemaRefs(node) {
 *
 * Only refs that carry a `$ref` pointer count, so a synthesized ref pointing at a sibling in the
 * same file (a union member created by name) is left out. That leaves exactly the set
-* `resolver.imports` emits.
+* `resolver.imports` emits. Refs inside `conditionals`, `contains` and `content` count only with
+* `checks: true`, for a plugin that prints those checks.
 *
 * @example
 * ```ts
@@ -1228,8 +1255,8 @@ function collectSchemaRefs(node) {
 * // ['Category', 'Tag']
 * ```
 */
-function collectImportedRefNames(node) {
-	return memo(importedRefNames, node, () => [...new Set(collectRefEntries(node).flatMap((entry) => entry.hasPointer ? [entry.name] : []))]);
+function collectImportedRefNames(node, { checks = false } = {}) {
+	return memo(checks ? importedCheckRefNames : importedRefNames, node, () => [...new Set(collectRefEntries(node, { checks }).flatMap((entry) => entry.hasPointer ? [entry.name] : []))]);
 }
 /**
 * Collects the names of all top-level schemas transitively used by a set of operations.