fix: handle circular OpenAPI schemas during conversion

[jarvis9443]

Fixes #453.

adc convert openapi only needs routing metadata, but the converter was dereferencing the whole OpenAPI document before conversion. For OpenAPI 3.0 documents with circular component schemas, that can make unrelated schema graphs fail before route conversion.

This changes the converter to upgrade the raw spec first, build a conversion-only document containing info, servers, paths, reusable path items, and x-adc-* fields, then dereference that smaller document. Request and response schema trees are left out because ADC config output does not consume them.

Route, service, upstream, label, and plugin metadata conversion behavior is preserved. A regression fixture covers the self-referencing schema from the issue.

Summary by CodeRabbit

Release Notes

• Improvements

  • Optimized OpenAPI document conversion process for improved performance and reliability when processing complex specifications.
  • Added support for self-referencing and recursive component schemas in OpenAPI definitions.

• Tests

  • Expanded test coverage for self-referencing schema conversion scenarios.

[coderabbitai]

Warning

Review limit reached

@jarvis9443, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 14 minutes and 37 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: de159cb7-92e0-415b-8783-530f3c149890

📥 Commits

Reviewing files that changed from the base of the PR and between e311dd2 and 4294efb.

📒 Files selected for processing (1)

• libs/converter-openapi/src/index.ts

📝 Walkthrough

Walkthrough

This PR fixes a stack overflow bug that occurred when converting OpenAPI 3.0.2 documents with self-referencing component schemas. The fix introduces document pruning helpers, restructures the parseOAS pipeline to apply pruning before dereferencing, updates route handling to inline path prefixes, and adds a test case validating the fix works with recursive schema structures.

Changes

OpenAPI Self-Referencing Schema Stack Overflow Fix

Layer / File(s)	Summary
Document pruning helpers libs/converter-openapi/src/index.ts	New internal utilities copy select top-level OpenAPI fields and prune path items to keep only $ref, servers, HTTP methods, and operation-level keys/extensions, creating a reduced document that prevents stack overflow during dereferencing.
parseOAS pipeline refactor libs/converter-openapi/src/index.ts	Restructured parseOAS to call upgrade(content) first, wrap the upgraded specification through createConversionDocument (pruning), then dereference the pruned result. Return type changed from prior dereference-first approach to res.schema cast as OpenAPIV3_1.Document.
Route typing and path prefix inlining libs/converter-openapi/src/index.ts	Explicitly type mapped route as ADCSDK.Route and inline service.path_prefix into each route.uris, removing path_prefix from the service object.
Test case with self-referencing schema libs/converter-openapi/test/assets/basic-8.yaml, libs/converter-openapi/test/basic.spec.ts	Added OpenAPI 3.0.2 test asset containing self-referencing SectorNode component schema (the reproduction case from issue #453), and Jest test case validating successful conversion to service with GET route and upstream configuration.

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 5 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
E2e Test Quality Review	⚠️ Warning	Test is unit-level only, not E2E; error handling is not tested; critical review issue unfixed: upgrade(content) called eagerly in of() at line 241, causing exceptions to escape synchronously be...	Add E2E test with actual API server, test error scenarios (invalid YAML, malformed schemas), and import defer from rxjs to wrap upgrade(content) to defer exception handling into the Observable stream as suggested in review comment.

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main fix: handling circular OpenAPI schemas during conversion, which is the core issue being resolved.
Linked Issues check	✅ Passed	The code changes directly address issue #453 by implementing the solution to prevent stack overflow when converting OpenAPI documents with self-referencing schemas.
Out of Scope Changes check	✅ Passed	All changes are scoped to fixing the circular schema handling: pruning pipeline in index.ts, test asset basic-8.yaml with the reproducer, and test case for regression coverage.
Security Check	✅ Passed	No security vulnerabilities found. PR is a stateless OpenAPI converter utility that: (1) doesn't expose credentials/secrets in logs (only logs HTTP methods and paths); (2) has no database operation...

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix-openapi-circular-453

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@libs/converter-openapi/src/index.ts`:
- Around line 241-246: The parseOAS implementation eagerly calls
upgrade(content) inside of(...), causing synchronous throws; change it to a lazy
Observable so upgrade(content) runs only on subscription (use RxJS defer or a
deferred factory returning the upgrade result) so errors become Observable
errors; update the pipeline starting at the current
of(upgrade(content).specification) to a deferred Observable that invokes
upgrade(content).specification when subscribed, keeping the downstream
map(dereference(...)) and error path intact (refer to parseOAS and the toADC
call sites to ensure behavior stays consistent).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 01f7a933-781c-4a95-85c3-ed206230ec3f

📥 Commits

Reviewing files that changed from the base of the PR and between d6ab29a and e311dd2.

📒 Files selected for processing (3)

• libs/converter-openapi/src/index.ts
• libs/converter-openapi/test/assets/basic-8.yaml
• libs/converter-openapi/test/basic.spec.ts

[jarvis9443]

The actionable inline issue from CodeRabbit was fixed in 4294efb and the thread is resolved. I am not adding an API-server E2E for this case because adc convert openapi is a local converter path; the regression is covered by the converter fixture and the CLI conversion path.