fix: prevent OOM when loading multi-file OpenAPI specs

[laurence79]

Summary

• Fixes a JavaScript heap out of memory crash when generating code from OpenAPI specs that use cross-file $ref references (e.g. models.yaml#/components/schemas/Foo)
• The document loader's inlining logic re-inlined the same external schemas under new pointer paths for every reference encountered, creating an exponentially growing document structure
• Adds deduplication by canonical reference key, deep-clones external schemas before insertion, and walks only the cloned subtree

Root cause

When the loader encounters a cross-file $ref, it copies the referenced schema into the root document at #/components/schemas/<title> and recursively walks the copy to resolve nested refs. However:

1. No deduplication: the walked array tracked pointer paths in the root document, not canonical external schema identities. The same external schema was inlined and walked once per unique pointer path where it was referenced.
2. Shared object references: refNode was inserted by reference (not cloned), so the cached external document was mutated by subsequent walks.
3. Walking from the root: AsyncJsonWalker.walk(doc, walkFn, newRef.pointer) could discover sibling schemas added by previous inlines, causing cascading re-processing.

With ~70 shared schemas referenced from ~35 endpoints, this created nested components/schemas trees (e.g. /components/schemas/CompanyStatus/components/schemas/ApproverList/components/schemas/...) growing without bound until OOM at ~4GB.

Fix

• Added inlinedRefs Set to track filename#pointer pairs that have already been inlined — each external schema is copied and walked exactly once
• JSON.parse(JSON.stringify(refNode)) deep-clones the node before inserting, preventing mutation of the cached source document
• Walk the cloned subtree directly rather than from a pointer path within doc

Testing

• Added load.spec.ts with 4 tests covering multi-file $ref resolution
• Added test fixtures (models.yaml + multi-file-api.yaml) exercising cross-file refs from multiple endpoints
• Verified against a production spec with 70+ schemas and 35+ endpoints — completes in <1s (previously OOM'd at 4GB)
• Existing v2 (swagger.json + user.json) example still generates correctly

---

Note

Medium Risk
Touches core OpenAPI document-loading/inlining logic; mistakes could break $ref rewriting or schema placement for multi-file specs, though changes are scoped and covered by new tests.

Overview
Prevents runaway growth/OOM when loading multi-file OpenAPI specs by deduplicating cross-file $ref inlining and avoiding repeated reinsertion of the same external schema.

load() now tracks already-inlined canonical refs, deep-clones referenced nodes before inserting into the root document, and walks only the cloned subtree; new fixtures and load.spec.ts tests assert schemas are inlined once, $refs are rewritten locally, and no nested components trees are produced.

^{Written by Cursor Bugbot for commit 9bb3be9. This will update automatically on new commits. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[cursor]

Deduplication skips inlining when target path differs

Low Severity

node.$ref = newRef.$ is set unconditionally (line 202), but jsonPointer.set(doc, newRef.pointer, cloned) only runs for the first encounter of a given canonicalKey. Since newRef depends on componentKeyForPointer(ptr), if the same external schema is referenced from contexts producing different component keys (e.g., one resolving to schemas, another to parameters), the second occurrence's $ref will point to a path that was never populated in doc, creating a dangling reference.

Additional Locations (1)

• src/helpers/document-loader/load.ts#L196-L199