@kubb/ast 5.0.0-alpha.73 → 5.0.0-alpha.74

package/dist/index.d.ts

@@ -2,7 +2,10 @@ import { t as __name } from "./chunk--u3MIqq1.js";
 
 //#region src/constants.d.ts
 /**
- * Traversal depth used by AST visitor utilities.
+ * Traversal depth for AST visitor utilities.
+ *
+ * - `'shallow'` — visits only the immediate node, skipping children.
+ * - `'deep'` — recursively visits all descendant nodes.
  */
 type VisitorDepth = 'shallow' | 'deep';
 declare const nodeKinds: {
@@ -25,15 +28,11 @@ declare const nodeKinds: {
   readonly break: "Break";
 };
 /**
- * Canonical schema type strings used by AST schema nodes.
- *
- * These values are used across the AST as stable discriminators
- * (for example `schema.type === schemaTypes.object`).
+ * Schema type discriminators used by all AST schema nodes.
  *
- * The map is grouped by intent:
- * - primitives (`string`, `number`, `boolean`, ...)
- * - structural/composite (`object`, `array`, `union`, ...)
- * - special OpenAPI-oriented types (`ref`, `datetime`, `uuid`, ...)
+ * These values serve as stable discriminators across the AST (e.g., `schema.type === schemaTypes.object`).
+ * Grouped by category: primitives (`string`, `number`, `boolean`), structural types (`object`, `array`, `union`),
+ * and format-specific types (`date`, `uuid`, `email`). Use `isScalarPrimitive()` to check for scalar types.
  */
 declare const schemaTypes: {
   /**
@@ -143,9 +142,16 @@ declare const schemaTypes: {
 };
 type ScalarPrimitive = 'string' | 'number' | 'integer' | 'bigint' | 'boolean';
 /**
- * Returns `true` when `type` is a scalar primitive schema type.
+ * Type guard that returns `true` when `type` is a scalar primitive schema type.
+ *
+ * Use this to check if a schema type can be directly assigned without wrapping (e.g., `string | number | boolean`).
  */
 declare function isScalarPrimitive(type: string): type is ScalarPrimitive;
+/**
+ * HTTP method identifiers used by operation nodes.
+ *
+ * Includes all standard HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE).
+ */
 declare const httpMethods: {
   readonly get: "GET";
   readonly post: "POST";
@@ -156,6 +162,12 @@ declare const httpMethods: {
   readonly options: "OPTIONS";
   readonly trace: "TRACE";
 };
+/**
+ * Common MIME types used in request/response content negotiation.
+ *
+ * Covers JSON, XML, form data, PDFs, images, audio, and video formats.
+ * Use these as keys when serializing request/response bodies.
+ */
 declare const mediaTypes: {
   readonly applicationJson: "application/json";
   readonly applicationXml: "application/xml";
@@ -3162,44 +3174,32 @@ declare function collect<T>(node: Node, options: CollectOptions<T>): Array<T>;
 //#endregion
 //#region src/utils.d.ts
 /**
- * Returns a merged schema view for a ref node, combining the resolved `node.schema`
- * (base from the referenced definition) with any usage-site sibling fields set directly
- * on the ref node (description, readOnly, nullable, deprecated, etc.).
+ * Merges a ref node with its resolved schema, giving usage-site fields precedence.
  *
- * Usage-site fields take precedence over the resolved schema's own fields when both are defined.
+ * Usage-site fields (`description`, `readOnly`, `nullable`, `deprecated`) on the ref node
+ * override the same fields in the resolved `node.schema`. Non-ref nodes are returned unchanged.
  *
- * For non-ref nodes the node itself is returned unchanged.
+ * @example
+ * ```ts
+ * // Ref with description override
+ * const ref = createSchema({ type: 'ref', ref: '#/components/schemas/Pet', description: 'A cute pet' })
+ * const merged = syncSchemaRef(ref)  // merges with resolved Pet schema
+ * ```
  */
 declare function syncSchemaRef(node: SchemaNode): SchemaNode;
 /**
- * Returns `true` when a schema is emitted as a plain `string` type.
- *
- * - `string`, `uuid`, `email`, `url`, `datetime` are always plain strings.
- * - `date` and `time` are plain strings when their `representation` is `'string'` rather than `'date'`.
+ * Type guard that returns `true` when a schema emits as a plain `string` type.
  *
- * @example
- * ```ts
- * isStringType(createSchema({ type: 'uuid' }))                          // true
- * isStringType(createSchema({ type: 'date', representation: 'date' }))  // false
- * ```
+ * Covers `string`, `uuid`, `email`, `url`, and `datetime` types. For `date` and `time`
+ * types, returns `true` only when `representation` is `'string'` rather than `'date'`.
  */
 declare function isStringType(node: SchemaNode): boolean;
 /**
  * Applies casing rules to parameter names and returns a new parameter array.
  *
- * The input array is not mutated.
- * If `casing` is not set, the original array is returned unchanged.
- *
- * Use this before passing parameters to schema builders so that property keys
- * in generated output match the desired casing while preserving
- * `OperationNode.parameters` for other consumers.
- *
- * @example
- * ```ts
- * const params = [createParameter({ name: 'pet_id', in: 'query', schema: createSchema({ type: 'string' }) })]
- * const cased = caseParams(params, 'camelcase')
- * // cased[0].name === 'petId'
- * ```
+ * Use this before passing parameters to schema builders so output property keys match
+ * the desired casing while preserving `OperationNode.parameters` for other consumers.
+ * The input array is not mutated. When `casing` is not set, the original array is returned unchanged.
  */
 declare function caseParams(params: Array<ParameterNode>, casing: 'camelcase' | undefined): Array<ParameterNode>;
 /**
@@ -3343,34 +3343,26 @@ type CreateOperationParamsOptions = {
   typeWrapper?: (type: string) => string;
 };
 /**
- * Converts an {@link OperationNode} into a {@link FunctionParametersNode}.
- *
- * Centralizes the per-plugin `getParams()` pattern. Provide a `resolver` for
- * type resolution and `extraParams` for plugin-specific trailing parameters.
+ * Converts an `OperationNode` into function parameters for code generation.
  *
- * @example
- * ```ts
- * const params = createOperationParams(node, {
- *   paramsType: 'inline',
- *   pathParamsType: 'inline',
- *   resolver: tsResolver,
- *   extraParams: [createFunctionParameter({ name: 'options', type: createParamsType({ variant: 'reference', name: 'Partial<RequestOptions>' }), default: '{}' })],
- * })
- * ```
+ * Centralizes parameter grouping logic for all plugins. Provide a `resolver` for type name resolution
+ * and `extraParams` for plugin-specific trailing parameters (e.g., `options` objects).
+ * Supports three grouping modes: `object` (single destructured param), `inline` (separate params),
+ * and `inlineSpread` (rest parameter). Use `CreateOperationParamsOptions` to fine-tune output.
  */
 declare function createOperationParams(node: OperationNode, options: CreateOperationParamsOptions): FunctionParametersNode;
 /**
- * Recursively extracts all string content embedded in a {@link CodeNode} tree.
+ * Extracts all string content from a `CodeNode` tree recursively.
  *
- * Includes text node values, and string attribute fields (`params`, `generics`,
- * `returnType`, `type`) that may reference identifiers needing imports.
- * Used by `createFile` to build the full source string for import filtering.
+ * Collects text node values, identifier references in string fields (`params`, `generics`, `returnType`, `type`),
+ * and nested node content. Used internally to build the full source string for import filtering.
  */
 declare function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): string;
 /**
- * Resolves the referenced schema name of a `ref` node, falling back through
- * `ref` → `name` → nested `schema.name`. Returns `undefined` for non-ref
- * nodes or when no name can be resolved.
+ * Resolves the schema name of a ref node, falling back through `ref` → `name` → nested `schema.name`.
+ *
+ * Returns `undefined` for non-ref nodes or when no name can be resolved. Use this to get a schema's
+ * identifier for type definitions or error messages.
  *
  * @example
  * ```ts
@@ -3380,56 +3372,31 @@ declare function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): st
  */
 declare function resolveRefName(node: SchemaNode | undefined): string | undefined;
 /**
- * Recursively collects every named schema referenced (transitively) from
- * `node` via `ref` edges. Refs are followed by name only — the resolved
- * `node.schema` of a ref is not traversed inline.
+ * Collects every named schema referenced (transitively) from a node via ref edges.
  *
- * @example
- * ```ts
- * const refs = collectReferencedSchemaNames(petSchema)
- * // => Set { 'Cat', 'Dog' }
- * ```
+ * Refs are followed by name only — the resolved `node.schema` is not traversed inline.
+ * Use this to determine schema dependencies, build reference graphs, or detect what schemas need to be emitted.
+ *
+ * @note Returns a Set of schema names for efficient membership testing.
  */
 declare function collectReferencedSchemaNames(node: SchemaNode | undefined, out?: Set<string>): Set<string>;
 /**
- * Identifies every named schema that participates in a circular dependency
- * chain — including direct self-loops (e.g. `TreeNode → TreeNode`) and indirect
- * cycles spanning multiple schemas (e.g. `Pet → Cat → Pet`).
- *
- * The returned set contains schema names. Plugins that translate schemas into
- * a host language can use this to wrap recursive positions in a deferred
- * construct (lazy getter, `z.lazy(() => …)`, etc.) and avoid runtime stack
- * overflows when the generated code is executed.
+ * Identifies all schemas that participate in circular dependency chains, including direct self-loops.
  *
- * Refs are followed by name only — `node.schema` (the resolved referent) is
- * not traversed inline, which keeps the algorithm linear in the size of the
- * schema graph.
+ * Returns a Set of schema names with circular dependencies. Use this to wrap recursive schema positions
+ * in deferred constructs (lazy getter, `z.lazy(() => …)`) to prevent infinite recursion when generated code runs.
+ * Refs are followed by name only, keeping the algorithm linear in the schema graph size.
  *
- * @example
- * ```ts
- * const circular = findCircularSchemas(inputNode.schemas)
- * if (circular.has('Pet')) {
- *   // emit lazy wrapper for any property whose schema references Pet
- * }
- * ```
+ * @note Call this once on the full schema graph, then use `containsCircularRef()` to check individual schemas.
  */
 declare function findCircularSchemas(schemas: ReadonlyArray<SchemaNode>): Set<string>;
 /**
- * Returns true when `node` (or anything nested within it) carries a `ref`
- * whose resolved name belongs to `circularSchemas`.
+ * Type guard returning `true` when a schema or anything nested within it contains a ref to a circular schema.
  *
- * When `excludeName` is provided, refs to that name are ignored — useful
- * when self-references are already handled separately from cross-schema
- * cycles (e.g. the faker plugin emits `undefined as any` for direct
- * self-recursion but a lazy getter for indirect cycles).
+ * Use `excludeName` to ignore refs to specific schemas (useful when self-references are handled separately).
+ * Commonly used with `findCircularSchemas()` to detect where lazy wrappers are needed in code generation.
  *
- * @example
- * ```ts
- * const circular = findCircularSchemas(schemas)
- * if (containsCircularRef(property.schema, { circularSchemas: circular, excludeName: 'Pet' })) {
- *   // emit `get foo() { return fakeCat() }` instead of eager call
- * }
- * ```
+ * @note Returns `true` for the first matching circular ref found; use for fast dependency checks.
  */
 declare function containsCircularRef(node: SchemaNode | undefined, {
   circularSchemas,

package/dist/index.js

@@ -26,15 +26,11 @@ const nodeKinds = {
 	break: "Break"
 };
 /**
-* Canonical schema type strings used by AST schema nodes.
+* Schema type discriminators used by all AST schema nodes.
 *
-* These values are used across the AST as stable discriminators
-* (for example `schema.type === schemaTypes.object`).
-*
-* The map is grouped by intent:
-* - primitives (`string`, `number`, `boolean`, ...)
-* - structural/composite (`object`, `array`, `union`, ...)
-* - special OpenAPI-oriented types (`ref`, `datetime`, `uuid`, ...)
+* These values serve as stable discriminators across the AST (e.g., `schema.type === schemaTypes.object`).
+* Grouped by category: primitives (`string`, `number`, `boolean`), structural types (`object`, `array`, `union`),
+* and format-specific types (`date`, `uuid`, `email`). Use `isScalarPrimitive()` to check for scalar types.
 */
 const schemaTypes = {
 	/**
@@ -143,7 +139,9 @@ const schemaTypes = {
 	never: "never"
 };
 /**
-* Primitive scalar schema types used when simplifying union members.
+* Scalar primitive schema types used for union simplification and type narrowing.
+*
+* Use `isScalarPrimitive()` to safely check whether a type is a scalar primitive.
 */
 const SCALAR_PRIMITIVE_TYPES = new Set([
 	"string",
@@ -153,11 +151,18 @@ const SCALAR_PRIMITIVE_TYPES = new Set([
 	"boolean"
 ]);
 /**
-* Returns `true` when `type` is a scalar primitive schema type.
+* Type guard that returns `true` when `type` is a scalar primitive schema type.
+*
+* Use this to check if a schema type can be directly assigned without wrapping (e.g., `string | number | boolean`).
 */
 function isScalarPrimitive(type) {
 	return SCALAR_PRIMITIVE_TYPES.has(type);
 }
+/**
+* HTTP method identifiers used by operation nodes.
+*
+* Includes all standard HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE).
+*/
 const httpMethods = {
 	get: "GET",
 	post: "POST",
@@ -168,6 +173,12 @@ const httpMethods = {
 	options: "OPTIONS",
 	trace: "TRACE"
 };
+/**
+* Common MIME types used in request/response content negotiation.
+*
+* Covers JSON, XML, form data, PDFs, images, audio, and video formats.
+* Use these as keys when serializing request/response bodies.
+*/
 const mediaTypes = {
 	applicationJson: "application/json",
 	applicationXml: "application/xml",
@@ -765,13 +776,17 @@ const plainStringTypes = new Set([
 	"datetime"
 ]);
 /**
-* Returns a merged schema view for a ref node, combining the resolved `node.schema`
-* (base from the referenced definition) with any usage-site sibling fields set directly
-* on the ref node (description, readOnly, nullable, deprecated, etc.).
+* Merges a ref node with its resolved schema, giving usage-site fields precedence.
 *
-* Usage-site fields take precedence over the resolved schema's own fields when both are defined.
+* Usage-site fields (`description`, `readOnly`, `nullable`, `deprecated`) on the ref node
+* override the same fields in the resolved `node.schema`. Non-ref nodes are returned unchanged.
 *
-* For non-ref nodes the node itself is returned unchanged.
+* @example
+* ```ts
+* // Ref with description override
+* const ref = createSchema({ type: 'ref', ref: '#/components/schemas/Pet', description: 'A cute pet' })
+* const merged = syncSchemaRef(ref)  // merges with resolved Pet schema
+* ```
 */
 function syncSchemaRef(node) {
 	const ref = narrowSchema(node, "ref");
@@ -785,16 +800,10 @@ function syncSchemaRef(node) {
 	});
 }
 /**
-* Returns `true` when a schema is emitted as a plain `string` type.
-*
-* - `string`, `uuid`, `email`, `url`, `datetime` are always plain strings.
-* - `date` and `time` are plain strings when their `representation` is `'string'` rather than `'date'`.
+* Type guard that returns `true` when a schema emits as a plain `string` type.
 *
-* @example
-* ```ts
-* isStringType(createSchema({ type: 'uuid' }))                          // true
-* isStringType(createSchema({ type: 'date', representation: 'date' }))  // false
-* ```
+* Covers `string`, `uuid`, `email`, `url`, and `datetime` types. For `date` and `time`
+* types, returns `true` only when `representation` is `'string'` rather than `'date'`.
 */
 function isStringType(node) {
 	if (plainStringTypes.has(node.type)) return true;
@@ -805,19 +814,9 @@ function isStringType(node) {
 /**
 * Applies casing rules to parameter names and returns a new parameter array.
 *
-* The input array is not mutated.
-* If `casing` is not set, the original array is returned unchanged.
-*
-* Use this before passing parameters to schema builders so that property keys
-* in generated output match the desired casing while preserving
-* `OperationNode.parameters` for other consumers.
-*
-* @example
-* ```ts
-* const params = [createParameter({ name: 'pet_id', in: 'query', schema: createSchema({ type: 'string' }) })]
-* const cased = caseParams(params, 'camelcase')
-* // cased[0].name === 'petId'
-* ```
+* Use this before passing parameters to schema builders so output property keys match
+* the desired casing while preserving `OperationNode.parameters` for other consumers.
+* The input array is not mutated. When `casing` is not set, the original array is returned unchanged.
 */
 function caseParams(params, casing) {
 	if (!casing) return params;
@@ -877,20 +876,12 @@ function resolveParamsType({ node, param, resolver }) {
 	});
 }
 /**
-* Converts an {@link OperationNode} into a {@link FunctionParametersNode}.
-*
-* Centralizes the per-plugin `getParams()` pattern. Provide a `resolver` for
-* type resolution and `extraParams` for plugin-specific trailing parameters.
+* Converts an `OperationNode` into function parameters for code generation.
 *
-* @example
-* ```ts
-* const params = createOperationParams(node, {
-*   paramsType: 'inline',
-*   pathParamsType: 'inline',
-*   resolver: tsResolver,
-*   extraParams: [createFunctionParameter({ name: 'options', type: createParamsType({ variant: 'reference', name: 'Partial<RequestOptions>' }), default: '{}' })],
-* })
-* ```
+* Centralizes parameter grouping logic for all plugins. Provide a `resolver` for type name resolution
+* and `extraParams` for plugin-specific trailing parameters (e.g., `options` objects).
+* Supports three grouping modes: `object` (single destructured param), `inline` (separate params),
+* and `inlineSpread` (rest parameter). Use `CreateOperationParamsOptions` to fine-tune output.
 */
 function createOperationParams(node, options) {
 	const { paramsType, pathParamsType, paramsCasing, resolver, pathParamsDefault, extraParams = [], paramNames, typeWrapper } = options;
@@ -1100,9 +1091,9 @@ function sortKey(node) {
 	return `${isArray}:${typeOnly}:${node.path}:${hasName}:${name}`;
 }
 /**
-* Deduplicates an array of `SourceNode` objects.
-* Named sources are deduplicated by `name + isExportable + isTypeOnly`.
-* Unnamed sources are deduplicated by object reference.
+* Deduplicates and merges `SourceNode` objects by `name + isExportable + isTypeOnly`.
+*
+* Unnamed sources are deduplicated by object reference. Returns a deduplicated array in original order.
 */
 function combineSources(sources) {
 	const seen = /* @__PURE__ */ new Map();
@@ -1113,8 +1104,10 @@ function combineSources(sources) {
 	return [...seen.values()];
 }
 /**
-* Deduplicates and merges an array of `ExportNode` objects.
-* Exports with the same path and `isTypeOnly` flag have their names merged.
+* Deduplicates and merges `ExportNode` objects by path and type.
+*
+* Named exports with the same path and `isTypeOnly` flag have their names merged into a single export.
+* Non-array exports are deduplicated by exact identity. Returns a sorted, deduplicated array.
 */
 function combineExports(exports) {
 	const result = [];
@@ -1154,9 +1147,12 @@ function combineExports(exports) {
 	return result;
 }
 /**
-* Deduplicates and merges an array of `ImportNode` objects.
-* Filters out unused imports (names not referenced in `source` or re-exported).
-* Imports with the same path and `isTypeOnly` flag have their names merged.
+* Deduplicates and merges `ImportNode` objects, filtering out unused imports.
+*
+* Retains imports that are referenced in `source` or re-exported. Imports with the same path and
+* `isTypeOnly` flag have their names merged. Returns a sorted, deduplicated, filtered array.
+*
+* @note Use this when combining imports from multiple files to avoid duplicate declarations.
 */
 function combineImports(imports, exports, source) {
 	const exportedNames = new Set(exports.flatMap((e) => Array.isArray(e.name) ? e.name : e.name ? [e.name] : []));
@@ -1202,11 +1198,10 @@ function combineImports(imports, exports, source) {
 	return result;
 }
 /**
-* Recursively extracts all string content embedded in a {@link CodeNode} tree.
+* Extracts all string content from a `CodeNode` tree recursively.
 *
-* Includes text node values, and string attribute fields (`params`, `generics`,
-* `returnType`, `type`) that may reference identifiers needing imports.
-* Used by `createFile` to build the full source string for import filtering.
+* Collects text node values, identifier references in string fields (`params`, `generics`, `returnType`, `type`),
+* and nested node content. Used internally to build the full source string for import filtering.
 */
 function extractStringsFromNodes(nodes) {
 	if (!nodes?.length) return "";
@@ -1226,9 +1221,10 @@ function extractStringsFromNodes(nodes) {
 	}).filter(Boolean).join("\n");
 }
 /**
-* Resolves the referenced schema name of a `ref` node, falling back through
-* `ref` → `name` → nested `schema.name`. Returns `undefined` for non-ref
-* nodes or when no name can be resolved.
+* Resolves the schema name of a ref node, falling back through `ref` → `name` → nested `schema.name`.
+*
+* Returns `undefined` for non-ref nodes or when no name can be resolved. Use this to get a schema's
+* identifier for type definitions or error messages.
 *
 * @example
 * ```ts
@@ -1242,15 +1238,12 @@ function resolveRefName(node) {
 	return node.name ?? node.schema?.name ?? void 0;
 }
 /**
-* Recursively collects every named schema referenced (transitively) from
-* `node` via `ref` edges. Refs are followed by name only — the resolved
-* `node.schema` of a ref is not traversed inline.
+* Collects every named schema referenced (transitively) from a node via ref edges.
 *
-* @example
-* ```ts
-* const refs = collectReferencedSchemaNames(petSchema)
-* // => Set { 'Cat', 'Dog' }
-* ```
+* Refs are followed by name only — the resolved `node.schema` is not traversed inline.
+* Use this to determine schema dependencies, build reference graphs, or detect what schemas need to be emitted.
+*
+* @note Returns a Set of schema names for efficient membership testing.
 */
 function collectReferencedSchemaNames(node, out = /* @__PURE__ */ new Set()) {
 	if (!node) return out;
@@ -1263,26 +1256,13 @@ function collectReferencedSchemaNames(node, out = /* @__PURE__ */ new Set()) {
 	return out;
 }
 /**
-* Identifies every named schema that participates in a circular dependency
-* chain — including direct self-loops (e.g. `TreeNode → TreeNode`) and indirect
-* cycles spanning multiple schemas (e.g. `Pet → Cat → Pet`).
-*
-* The returned set contains schema names. Plugins that translate schemas into
-* a host language can use this to wrap recursive positions in a deferred
-* construct (lazy getter, `z.lazy(() => …)`, etc.) and avoid runtime stack
-* overflows when the generated code is executed.
+* Identifies all schemas that participate in circular dependency chains, including direct self-loops.
 *
-* Refs are followed by name only — `node.schema` (the resolved referent) is
-* not traversed inline, which keeps the algorithm linear in the size of the
-* schema graph.
+* Returns a Set of schema names with circular dependencies. Use this to wrap recursive schema positions
+* in deferred constructs (lazy getter, `z.lazy(() => …)`) to prevent infinite recursion when generated code runs.
+* Refs are followed by name only, keeping the algorithm linear in the schema graph size.
 *
-* @example
-* ```ts
-* const circular = findCircularSchemas(inputNode.schemas)
-* if (circular.has('Pet')) {
-*   // emit lazy wrapper for any property whose schema references Pet
-* }
-* ```
+* @note Call this once on the full schema graph, then use `containsCircularRef()` to check individual schemas.
 */
 function findCircularSchemas(schemas) {
 	const graph = /* @__PURE__ */ new Map();
@@ -1309,21 +1289,12 @@ function findCircularSchemas(schemas) {
 	return circular;
 }
 /**
-* Returns true when `node` (or anything nested within it) carries a `ref`
-* whose resolved name belongs to `circularSchemas`.
+* Type guard returning `true` when a schema or anything nested within it contains a ref to a circular schema.
 *
-* When `excludeName` is provided, refs to that name are ignored — useful
-* when self-references are already handled separately from cross-schema
-* cycles (e.g. the faker plugin emits `undefined as any` for direct
-* self-recursion but a lazy getter for indirect cycles).
+* Use `excludeName` to ignore refs to specific schemas (useful when self-references are handled separately).
+* Commonly used with `findCircularSchemas()` to detect where lazy wrappers are needed in code generation.
 *
-* @example
-* ```ts
-* const circular = findCircularSchemas(schemas)
-* if (containsCircularRef(property.schema, { circularSchemas: circular, excludeName: 'Pet' })) {
-*   // emit `get foo() { return fakeCat() }` instead of eager call
-* }
-* ```
+* @note Returns `true` for the first matching circular ref found; use for fast dependency checks.
 */
 function containsCircularRef(node, { circularSchemas, excludeName }) {
 	if (!node || circularSchemas.size === 0) return false;